DEV Community

Raj javiya
Raj javiya

Posted on

I Built GuideFlow: A Modern Android Onboarding SDK in Kotlin

#devchallenge #weekendchallenge

DEV Weekend Challenge: Passion Edition Submission

This is a submission for Weekend Challenge: Passion Edition

🚀 GuideFlow – Building the Android Onboarding SDK I Always Wanted

Every Android developer has probably built an onboarding or feature-tour system at least once. I certainly have—and every time, I found myself solving the same problems: spotlight overlays, tooltip positioning, scrolling to views, handling different screen types, remembering completed tours, and making everything feel polished.

Instead of rebuilding the same solution for every project, I decided to create something reusable for the Android community.

That's how GuideFlow was born.

GuideFlow is a modern, lightweight, and flexible Android SDK that helps developers build beautiful onboarding experiences with just a few lines of Kotlin.

Fully built in Kotlin, 100% host-agnostic, completely XML-free under the hood, and designed with developer experience in mind.

What I Built

GuideFlow is an open-source Android SDK for creating interactive onboarding flows and feature tours.

Rather than spending days implementing overlays, animations, tooltip positioning, scrolling logic, and state management, developers can integrate GuideFlow in minutes and focus on building great user experiences.

GuideFlow is now published on Maven Central, making it easy to integrate into any Android project using a single Gradle dependency.

Key Features

  • 🎯 Works with Activity, Fragment, DialogFragment, BottomSheetDialogFragment, and standalone View.
  • ✨ Beautiful spotlight animations with multiple cutout shapes.
  • 🧩 Automatic scrolling for RecyclerView, ScrollView, NestedScrollView, and ViewPager2.
  • 🎨 Fully customizable themes with Material You support.
  • ♿ Accessibility-first with automatic TalkBack announcements.
  • 💾 Built-in persistence to remember completed tours.
  • 🔀 Conditional onboarding steps.
  • ➕ Runtime step insertion and removal.
  • ▶️ Resume interrupted tours automatically.
  • 📄 JSON-driven onboarding for remote configuration.
  • 🖌️ Fully customizable tooltip UI.

Demo

🚀 Available on Maven Central

dependencies {
    implementation("io.github.javiyaraj:guideflow:1.0.1")
}
Enter fullscreen mode Exit fullscreen mode

📦 Maven Central

https://central.sonatype.com/artifact/io.github.javiyaraj/guideflow

💻 GitHub Repository

https://github.com/JAVIYARAJ/guide_flow_sdk

Example:

GuideFlow.with(this)
    .setTourId("home_onboarding")
    .setTheme(TourTheme.dark())
    .addStep(
        GuideStep(
            targetView = fab,
            title = "Create New Item",
            description = "Tap here to add a new item."
        )
    )
    .addStep(
        GuideStep(
            targetView = menu,
            title = "Settings",
            description = "Customize your experience here."
        )
    )
    .start()
Enter fullscreen mode Exit fullscreen mode

Code

The complete source code is available on GitHub:

GitHub Repository

https://github.com/JAVIYARAJ/guide_flow_sdk

GuideFlow is open source under the MIT License, and contributions, bug reports, feature requests, and feedback are always welcome.

How I Built It

GuideFlow is written entirely in Kotlin with a strong focus on performance, flexibility, and developer experience.

Instead of creating another simple tooltip library, I wanted to solve the real-world challenges Android developers face while implementing onboarding.

Kotlin DSL

The SDK uses a fluent Kotlin DSL, making onboarding flows easy to read and write.

GuideFlow.with(this)
    .addStep(...)
    .addStep(...)
    .start()
Enter fullscreen mode Exit fullscreen mode

The API was designed to feel natural while remaining highly configurable.

Smart Tour Engine

Instead of displaying every step sequentially, GuideFlow evaluates each step before showing it.

This makes it possible to:

  • Skip unavailable features automatically.
  • Show Premium-only onboarding.
  • Personalize tours for different users.
  • Dynamically react to application state.

Example:

GuideStep(
    targetView = premiumCard,
    title = "Premium Analytics",
    description = "Available for premium users.",
    condition = { user.isPremium() }
)
Enter fullscreen mode Exit fullscreen mode

Runtime Tour Modification

Applications change while users interact with them.

GuideFlow allows developers to modify tours at runtime.

tour.addStepAfter("login_step", profileStep)

tour.removeStep("premium_step")
Enter fullscreen mode Exit fullscreen mode

This enables highly dynamic onboarding experiences.

JSON-Driven Tours

One feature I'm especially proud of is the ability to build complete onboarding flows from JSON.

This allows developers to:

  • Update onboarding remotely.
  • Run A/B experiments.
  • Build server-controlled tutorials.
  • Launch marketing campaigns without releasing a new app update.

Host-Agnostic Architecture

GuideFlow isn't tied to Activities.

It works seamlessly with:

  • Activity
  • Fragment
  • DialogFragment
  • BottomSheetDialogFragment
  • Standalone View

This flexibility required designing the rendering engine independently from the Android component hosting the tour.

Accessibility

Accessibility wasn't treated as an optional feature.

GuideFlow automatically announces every onboarding step through TalkBack, ensuring visually impaired users receive the same guided experience.

Persistence

Nothing is more frustrating than seeing the same onboarding every time an app launches.

GuideFlow automatically remembers completed tours and only shows them again when developers explicitly choose to reset them.

Challenges I Faced

Building GuideFlow involved solving much more than drawing spotlight animations.

Some of the biggest challenges included:

  • Supporting multiple Android UI containers.
  • Correctly calculating overlay positions.
  • Automatically scrolling nested containers.
  • Handling RecyclerView items that aren't currently visible.
  • Maintaining smooth animations without sacrificing performance.
  • Designing a simple API while supporting advanced features.
  • Creating an architecture that would remain maintainable as the SDK grows.

Every challenge helped shape the final architecture and API.

Why This Project Matters to Me

I genuinely enjoy building tools that help other developers.

Throughout my Android journey, I've learned so much from open-source libraries, and GuideFlow is my way of giving something back to the community.

Publishing GuideFlow to Maven Central was a huge milestone. It transformed a personal side project into a reusable SDK that any Android developer can integrate into production with a single dependency.

This project has taught me a tremendous amount about SDK design, Android rendering, API design, accessibility, and developer experience.

What's Next?

GuideFlow is just getting started.

My roadmap includes:

  • 🎨 Jetpack Compose support.
  • 📱 More sample applications.
  • 🌍 Better documentation.
  • ⚡ Performance improvements.
  • 🧪 Expanded test coverage.
  • 🤝 Community contributions.
  • 💡 More customization options.

Prize Categories

I'm submitting this as a general Weekend Challenge entry.

Thank you for taking the time to read about GuideFlow!

If you're an Android developer, I'd love to hear your thoughts, suggestions, or feature ideas.

⭐ If you find the project useful, please consider starring the repository on GitHub. It helps the project reach more developers and motivates me to keep improving it.

Happy coding! 🚀

Top comments (0)