Android Compose SDK Instrumentation- Automated Screen Tracking

Introduction

The Blue Triangle SDK 2.19.6 and above can automatically track Jetpack Compose screens when used with the Blue Triangle Gradle Plugin. No manual screen-tracking code is required.

How to Use

Configure the Plugin Repository

Add the Maven repository and plugin resolution strategy to your project's settings.gradle file:

Groovy

pluginManagement {
    repositories {
        //...
        maven { url = uri("https://jitpack.io") }
    }

    resolutionStrategy {
        eachPlugin {
            if (requested.id.id == "com.github.blue-triangle-tech.btt-gradle-plugin") {
                useModule(
                    "com.github.blue-triangle-tech:btt-gradle-plugin:${requested.version}"
                )
            }
        }
    }
}

Apply the Plugin

Add the Blue Triangle Gradle Plugin to your application's build.gradle file:

Groovy

plugins {
    //...
    id("com.github.blue-triangle-tech.btt-gradle-plugin") version "1.0.0"
}

How It Works

For Android applications built with Jetpack Compose and using Android's Navigation Component, the Blue Triangle Gradle Plugin automatically installs a navigation listener during the build process. No application code changes are required.

During compilation, the plugin uses bytecode instrumentation to hook directly into NavController, the component responsible for handling navigation between screens. The plugin attaches a listener that reports navigation events to the Blue Triangle SDK.

The screen name is derived from the route string defined in your NavGraph. For parameterised routes such as:

detail/{userId}

the raw route template (detail/{userId}) is reported as the screen name. This ensures consistent and predictable screen naming across all sessions.

Decompose :

If app uses Decompose library the Blue Triangle Gradle Plugin supports screen tracking for the Decompose library from version 3.0.0 and above.

Plugin uses bytecode instrumentation to hook directly into childStack method of com.arkivanov.decompose.router.stack.ChildStackFactor class to track screen navigation.

We use class name fromchildStack as screen name.

Troubleshooting

Verify Instrumentation

To verify that Blue Triangle Gradle instrumentation is being applied during the build process, enable debug logging in your application's build.gradle file:

bttOptions {
    debugLog = true
}

When enabled, the plugin outputs additional instrumentation details to the build logs. These logs can be used to confirm that Compose Navigation tracking has been successfully injected.

Compose Navigation tracking is enabled by default. To disable automatic screen tracking, add the following configuration to your application's build.gradle file:

bttOptions {
    composeNavigationInjectionEnabled = false
}