DEV Community: Antonio Huerta Reyes

Introducing TourCompose: The Easiest Way to Add Interactive Tours to Your Android Compose App (Without Losing Your Sanity)

Antonio Huerta Reyes — Sun, 03 Aug 2025 01:03:15 +0000

I get it – you're busy, you want to see results NOW, and you probably have 17 other tabs open. So here's what you came for:

🎯 Live Demo: Try it on GitHub

📦 Repository: github.com/AntonioHReyes/TourCompose

⚡ Quick Start: Just add implementation("com.github.AntonioHReyes:TourCompose:1.0.1") to your gradle

Got 2 minutes? Copy-paste the complete working example below and you'll have a working tour in your app.

Want the full story and all the juicy details? Keep reading – I promise it's worth it (and slightly entertaining). Otherwise, you know what to do. 👇

🤷‍♂️ The Full Story (For Those Who Like Context)

Let's be honest – adding onboarding tours to your Android app has traditionally been about as fun as debugging a null pointer exception at 3 AM. You've probably been there: wrestling with complex libraries, writing endless configuration files, and somehow ending up with tour bubbles that look like they time-traveled from 2010.

Well, grab your coffee ☕ and prepare to be pleasantly surprised. Meet TourCompose – the library that finally makes creating beautiful app tours as easy as it should have been all along.

🤔 The Problem We All Know Too Well

Picture this: Your PM walks over (or pings you on Slack if you're lucky enough to work remotely) and says, "Hey, can we add some onboarding to help users understand the app? Should be super quick, right?"

Internal screaming intensifies

You know what comes next:

Hours of documentation reading 📚
Complex XML configurations that make you question your life choices
Tour bubbles that somehow always appear in the wrong place
Styling that looks like it was designed by a caffeinated developer at 2 AM (spoiler: it probably was)
That one edge case where the tour breaks completely, but only on Samsung devices

Sound familiar? Yeah, we've all been there.

🚀 Enter TourCompose: Your New Best Friend

TourCompose was born from the simple idea that creating app tours shouldn't require a computer science degree. It's designed by developers, for developers who just want things to work without having to sacrifice their weekends to the onboarding gods.

What Makes It Special?

Zero complex setup – Because life's too short for 50-line configuration files
Works with Material Theme out of the box – Your designer will actually thank you
Flexible but not overwhelming – Customize when you need to, ignore when you don't
Actually tested in real apps – Not just in "hello world" examples

📦 Setup So Easy, Your Intern Could Do It

First, add this to your app's build.gradle.kts (yes, that's really all you need):

dependencies {
    implementation("com.github.AntonioHReyes:TourCompose:1.0.1")
}

Then add JitPack to your settings.gradle.kts (because apparently we all agreed that having 47 different repositories is totally normal):

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") } // The hero we need
    }
}

That's it. No, seriously. No additional permissions, no manifest entries, no sacrificial offerings to the Android gods.

💡 The "Holy Grail" Example: Copy, Paste, Ship

Remember how I mentioned this should be easy? Here's a complete, working example that you can literally copy and paste into a new project and it'll work. I'm not kidding – I actually tested this one:

MainActivity.kt


import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import com.tonyakitori.apps.tourcompose.TourCompose
import com.tonyakitori.apps.tourcompose.controller.TourComposeController
import com.tonyakitori.apps.tourcompose.controller.TourComposeStep
import com.tonyakitori.apps.tourcompose.controller.TourComposeWrapper
import com.tonyakitori.apps.tourcompose.settings.bubbleContent.bubbleContentBasicSettings
import java.util.UUID

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MaterialTheme {
                val tourController = remember { SimpleTourController() }

                TourComposeWrapper(tourController = tourController) {

                    val currentStep by tourController.currentStep.collectAsState(initial = null)

                    Column(
                        modifier = Modifier
                            .fillMaxSize()
                            .padding(32.dp),
                        verticalArrangement = Arrangement.spacedBy(32.dp),
                        horizontalAlignment = Alignment.CenterHorizontally
                    ) {

                        Text(
                            text = "Welcome to my awesome app!",
                            style = MaterialTheme.typography.headlineMedium,
                            modifier = Modifier.tourStepIndex("welcome-tour", 0)
                        )

                        Text(
                            text = "This app does amazing things that will change your life, cure your anxiety, and probably make you a better person.",
                            style = MaterialTheme.typography.bodyLarge,
                            modifier = Modifier.padding(16.dp)
                        )

                        Button(
                            onClick = {
                                // This button obviously does something super important
                                println("Button clicked! 🎉")
                            },
                            modifier = Modifier.tourStepIndex("welcome-tour", 1)
                        ) {
                            Text("Do Something Amazing")
                        }

                        Card(
                            modifier = Modifier
                                .fillMaxWidth()
                                .tourStepIndex("welcome-tour", 2)
                        ) {
                            Column(modifier = Modifier.padding(16.dp)) {
                                Text(
                                    text = "Pro Feature™",
                                    style = MaterialTheme.typography.titleMedium
                                )
                                Text(
                                    text = "This card contains features so advanced that we needed a tour just to explain them.",
                                    style = MaterialTheme.typography.bodyMedium
                                )
                            }
                        }

                        Spacer(modifier = Modifier.weight(1f))

                        Button(
                            onClick = { tourController.startTour("welcome-tour") },
                            colors = ButtonDefaults.buttonColors(
                                containerColor = MaterialTheme.colorScheme.secondary
                            )
                        ) {
                            Text("🎯 Start the Tour")
                        }
                    }

                    // Here's where the magic happens ✨
                    TourCompose(
                        componentRectArea = currentStep?.componentRect,
                        bubbleContentSettings = currentStep?.bubbleContentSettings
                    )
                }
            }
        }
    }
}

// This controller is so simple, it's almost embarrassing how easy this is
class SimpleTourController : TourComposeController() {
    init {
        addTour(
            flowId = "welcome-tour",
            steps = listOf(
                TourComposeStep(
                    id = UUID.randomUUID().toString(),
                    bubbleContentSettings = bubbleContentBasicSettings(
                        title = "👋 Hey There!",
                        description = "This is your app's main title. It's probably the first thing users see, so we made it big and friendly. Good choice!",
                        primaryButtonText = "Makes Sense",
                        onPrimaryClick = { nextStep() },
                        onDismiss = { stopTour() }
                    )
                ),
                TourComposeStep(
                    id = UUID.randomUUID().toString(),
                    bubbleContentSettings = bubbleContentBasicSettings(
                        title = "🚀 The Action Button",
                        description = "This button is where the magic happens. Click it to do something amazing (results may vary, but we're optimistic).",
                        primaryButtonText = "Got It!",
                        secondaryButtonText = "Wait, Go Back",
                        onPrimaryClick = { nextStep() },
                        onSecondaryClick = { previousStep() },
                        onDismiss = { stopTour() }
                    )
                ),
                TourComposeStep(
                    id = UUID.randomUUID().toString(),
                    bubbleContentSettings = bubbleContentBasicSettings(
                        title = "💎 Premium Content",
                        description = "This card showcases your premium features. It's fancy, it's important, and now your users know exactly where to find it!",
                        primaryButtonText = "Awesome, I'm Done!",
                        secondaryButtonText = "Show Me Again",
                        onPrimaryClick = { stopTour() },
                        onSecondaryClick = { previousStep() },
                        onDismiss = { stopTour() }
                    )
                )
            )
        )
    }
}

🎉 Run It and Watch the Magic

Seriously, that's it. Copy that code, create a new Compose project, paste it in, and hit run. You'll get:

Beautiful, themed tour bubbles that actually look good ✨
Navigation that just works (forward, backward, dismiss) 🔄
Automatic component highlighting that finds your UI elements like a GPS for tours 📍

🎨 But Wait, There's More! (Customization Without the Headache)

The "I Just Want Different Colors" Solution and the "I Want It to Match My Theme" Solution

// Your designer will think you're a wizard 🧙‍♂️
val contentBubbleColors = defaultBubbleContentColors().copy(
    titleTextColor = MaterialTheme.colorScheme.error
)

The "I Need This Tour to Look Like It Came From the Future" Solution

TourCompose(
    componentRectArea = currentStep?.componentRect,
    bubbleContentSettings = currentStep?.bubbleContentSettings,
    tourComposeProperties = TourComposeProperties.getDefaultInstance().copy(
        spotlightColors = DefaultSpotlightColors(
            overlayBackgroundColor = Color.Black.copy(alpha = 0.9f),
            overlayBorderColor = Color.Cyan
        ),
        dialogBubbleColors = DefaultDialogBubbleColors(
            backgroundColor = Color.Black,
            borderColor = Color.Cyan
        )
    )
)

🤓 For the Overachievers: Advanced Features

Smart Component Targeting

Just slap .tourStepIndex("your-tour-id", stepNumber) on any Composable and boom – it's part of your tour:

// Works on literally anything
Text("Hello", modifier = Modifier.tourStepIndex("intro", 0))
Button(onClick = {}, modifier = Modifier.tourStepIndex("intro", 1)) {}
LazyColumn(modifier = Modifier.tourStepIndex("intro", 2)) {}
YourCustomComposable(modifier = Modifier.tourStepIndex("intro", 3))

Multiple Tours (Because Why Not?)

// Welcome tour for new users
tourController.startTour("welcome-tour")

// Feature tour for when you add something cool
tourController.startTour("new-feature-tour")

// "Please rate us" tour for when you're feeling brave
tourController.startTour("desperate-for-ratings-tour")

Custom Bubble Content (For the Creative Souls)

Want to add progress bars, ratings, custom buttons, or a dancing cat GIF? TourCompose supports custom bubble content that can be as wild as your imagination (and your designer's caffeine level).

🎯 Getting Started (The TL;DR Version)

Add the dependency (2 lines in your gradle files)
Copy the example above (literally copy-paste, we won't judge)
Run it and smile (because it actually works)
Customize to your heart's content (or don't, the defaults are pretty nice)
Ship it (and maybe buy yourself a coffee to celebrate)

🔗 Links for the Impatient

Repository: github.com/AntonioHReyes/TourCompose
License: MIT (because we're not monsters)
Documentation: In the README (and it's actually helpful)

🚀 Final Thoughts

Creating good onboarding shouldn't be harder than building the actual app features. TourCompose exists because we got tired of fighting with tour libraries instead of building cool stuff.

Whether you're a solo indie developer building the next big thing, or part of a team shipping features to millions of users, TourCompose has your back. It's simple enough for quick prototypes and powerful enough for production apps.

So go ahead, add those tours your PM has been asking for. Make your app more user-friendly. Help your users discover features they didn't know existed. And do it all without losing your sanity or your weekend.

Your users (and your mental health) will thank you. 🙌

Ready to make onboarding tours that don't suck? Give TourCompose a spin – we promise it's more fun than debugging memory leaks!

P.S. – If you end up using TourCompose and it saves you time, star the repo. It makes us feel good about our life choices and motivates us to keep making cool stuff. Plus, your GitHub activity graph will look more impressive. Win-win! ⭐

CitRep - Android + Appwrite - Hackathon

Antonio Huerta Reyes — Tue, 10 May 2022 15:50:25 +0000

Overview of My Submission

CitRep is the prototype of an application to send complaints to a municipality, it is designed to speed up the complaint processes in the cities and towns of Mexico.

This app is designed with a clean architecture pattern and uses kotlin as its programming language.

The app is a prototype of a bigger idea and works as a preamble for the creation of the final version, before this I must admit that I had not heard of appwrite, however, with this hackathon I have learned a lot from this platform and I am delighted with the speed of development that I provide.

This application use the next appwrite features:

Create account
Create session with user and password
Delete Session
Get Account
Email verification
Get avatar with the name
Database list documents
RealTime
Create and save a new document
Upload and download image from appwrite bucket

Submission Category:

Mobile Moguls

Link to Code

AntonioHReyes / CitRep-appwrite

CitRep-appwrite

CitRep is the prototype of an application to send complaints to a municipality, it is designed to speed up the complaint processes in the cities and towns of Mexico

The application is designed by clean arquitecture pattern.

TechStack

Setup

Install appwrite in your local docker
Replace projectId and endpoint url in build.gradle
Generate a post and notifications collections and replace ids in build.gradle
Create a bucket and replace id in build.gradle

Appwrite features implemented

Create account
Create session with user and password
Delete Session
Get Account
Email verification
Get avatar with the name
Database list documents
RealTime
Create and save a new document
Upload and download image from appwrite bucket

Screen gifs

Signup

Post simple

Post with images

Navigation

Email verification flow

View on GitHub

Additional Resources / Info

Here are some flows implemented within the application

Signup

Navigation

Publish a simple post

Publish a post with images

Email verification flow

SetInterval en Android con Kotlin

Antonio Huerta Reyes — Sat, 19 Mar 2022 20:26:23 +0000

Durante mis inicios como desarrollador en más de una ocasión me encontré con el problema de tener que realizar alguna operación repetitiva cada «N» cantidad de tiempo, por aquellos días mis mejores soluciones dentro del mundo Android rondaban el crear una instancia de la clase Timer y una TimerTask así cuando esta terminara, reiniciaba una vez más el proceso.

Sin embargo como se puede suponer esta no es la mejor manera de realizarlo, dentro de Android gracias al profiler podía detectar que al estar haciendo este proceso con una función, el mismo se estaba convirtiendo en uno recursivo y por ende el consumo de memoria aunque pequeño crecía.

Pasado algún tiempo y leyendo la documentación de Kotlin en busca de mejorar mis soluciones y aprender más sobre el lenguaje me encontré con una herramienta que desde ese entonces me ha ayudado a mejorar mi programación cuando de intervalos se trata.

Dentro de Kotlin existe una biblioteca que proporciona herramientas útiles para la programación concurrente.

La programación concurrente es la ejecución simultánea de múltiples tareas interactivamente. Estas tareas pueden ser un conjunto de procesos o hilos de ejecución creados por un único programa.

Por ahora nos centraremos en una función que sera fixedRateTimer, en pocas palabras esta función crea un temporizador que ejecuta la acción especificada periódicamente, comenzando después del initialDelay especificado (expresado en milisegundos) y con el intervalo de milisegundos de período entre el inicio de la tarea anterior y el inicio de la siguiente.

A continuación les comparto un ligero ejemplo donde imprimiremos un mensaje de Hola mundo cada 5 segundos

El resultado seria el siguiente:

Así mismo esta función retorna una instancia de Timer con lo cual podemos obtener una referencia y cancelar el proceso una vez que nuestro trabajo repetitivo haya finalizado. Quedando una nueva versión del código en donde queremos finalizar el trabajo tras 5 repeticiones de la siguiente manera.

Esta misma función puede aceptar aparte de un delay al inicio también una fecha exacta para ejecutarse, te recomiendo leer más en la documentación oficial para conocer todas las posibilidades que existen.

Espero te haya gustado este articulo, nos seguimos viendo en el futuro.

SetTimeOut en Android

Antonio Huerta Reyes — Sat, 04 Dec 2021 20:54:19 +0000

En muchas ocasiones como desarrolladores Android nos hemos encontrado con la necesidad de realizar un proceso pasado cierta cantidad de tiempo o de realizar una cuenta regresiva que permita realizar una acción, en muchos de estos casos solemos hacer uso de los Handler o posiblemente de la funcionalidad delay en las coroutines de kotlin.

En esta ocasión traigo una alternativa que me ha funcionado exitosamente para muchas de mis implementaciones y que puede ser de utilidad también para muchos desarrolladores Android.

fun setTimeOut(handleFunction: () -> Unit, delay: Long): CountDownTimer {

    val timer = object: CountDownTimer(delay, 1000){
        override fun onFinish() {
            CoroutineScope(Dispatchers.Main).launch {
                handleFunction()
                cancel()
            }
        }

        override fun onTick(p0: Long) {}
    }

    timer.start()

    return timer
}

fun clearTimeOut(timer: CountDownTimer){
    try {
        timer.cancel()
    }catch (e: Exception){
        Log.e("Error", e.toString())
    }
}

Esta alternativa tiene como base el uso de la clase CountDownTimer de Android que en la propia definición de la documentación de Android es:

Schedule a countdown until a time in the future, with regular notifications on intervals along the way. Example of showing a 30 second countdown in a text field

Dicha clase nos permite programar una cuenta regresiva hasta un momento en el futuro con notificaciones regulares de los intervalos, y como se puede observar esta alternativa hace uso de funciones al estilo de JavaScript.

Nuestra función setTimeOut recibe como parámetros la función que se desea ejecutar tras determinado tiempo, este tiempo viene como el segundo parámetro el cual define en cuantos milisegundos deseas ejecutar la acción.

El segundo parámetro de la instancia de CountDownTimer es el intervalo que estará ejecutando el método onTick, en mi ejemplo lo he definido a un segundo, esta función a su ves regresa la instancia de CountDownTimer creada para su manipulación desde donde se llame la función o para hacer uso de la segunda función en el ejemplo.

La función clearTimeOut permite detener la ejecución de nuestro CountDownTimer antes de que este finalice su tarea.

Un ejemplo practico para estas dos funciones puede ser un buscador con conexión a una RestApi en donde deseamos llamar al endpoint que nos regresa los datos filtrados tras un determinado tiempo que se detecte que el usuario dejo de escribir.

En dicho caso haríamos el siguiente ejemplo:

    private lateinit var timeOutRef: CountDownTimer

    private fun setUpSearchEditText(){
        binding.searchInput.doOnTextChanged { text, start, before, count ->
            if(this::timeOutRef.isInitialized){
                clearTimeOut(this.timeOutRef)
            }

            timeOutRef = setTimeOut({ Log.d("TimeOut","Enviar al endpoint") }, 1000)
        }
    }

Espero que este pequeño blog y funciones sean de ayuda para otros programadores como lo fue en mi caso, de la misma manera les dejo el enlace al gist por si desean copiarlo y adaptarlo a sus necesidades.

https://gist.github.com/AntonioHReyes/73a3184362dc8d9a65157070695d87cb