Guides and Surveys Android SDK

Amplitude's Guides and Surveys Android SDK enables you to deploy Guides and Surveys in your Android applications.

Requirements

The Guides and Surveys Android SDK requires:

• Android API Level 24 (Android 7.0)+
• Kotlin 1.8.22+

You can use Guides and Surveys independently of Amplitude Analytics.

Install and initialize the SDK

Guides and Surveys supports different installation options to work best with your existing Amplitude implementation, if you have one.

Using Amplitude Analytics Android-Kotlin SDK

If your app uses the Amplitude Analytics Android-Kotlin SDK, make sure you are using version 1.0 or later. Then add the following dependencies to your application's build.gradle.kts file:

dependencies {
    // Amplitude Engagement SDK
    implementation("com.amplitude:amplitude-engagement-android:3.+")

    // Amplitude Analytics SDK (required dependency)
    implementation("com.amplitude:analytics-android:1.+")
}

Initialize the SDK

import com.amplitude.android.engagement.AmplitudeEngagement
import com.amplitude.android.engagement.AmplitudeInitOptions

// Initialize the SDK
val amplitudeEngagement = AmplitudeEngagement(
    context = applicationContext,
    apiKey = "YOUR_API_KEY",
    options = AmplitudeInitOptions()
)

// Add the plugin to your Amplitude instance
val amplitude = Amplitude(applicationContext)
amplitude.add(amplitudeEngagement.getPlugin())

This call uses the Amplitude Analytics Android SDK's plugin system to integrate Guides and Surveys with your existing Analytics setup. Adding the plugin means Guides and Surveys initializes alongside Analytics, shares the same API key and user identity, and communicates with it directly. You don't need to call boot separately.

Configuration options

Not using Amplitude Analytics Android-Kotlin SDK 1.0+

If your app doesn't use the Amplitude Analytics Android-Kotlin SDK 1.0+, you can still install Guides and Surveys, but you need to call .boot directly instead of using the Analytics SDK plugin system.

Add the following dependencies to your application's build.gradle.kts file:

dependencies {
    // Amplitude Engagement SDK
    implementation("com.amplitude:amplitude-engagement-android:2.+")
}

Initialize the SDK

import com.amplitude.android.engagement.AmplitudeEngagement
import com.amplitude.android.engagement.AmplitudeInitOptions

// Initialize the SDK
val amplitudeEngagement = AmplitudeEngagement(
    context = applicationContext,
    apiKey = "YOUR_API_KEY",
    options = AmplitudeInitOptions()
)

Configuration options

Boot the SDK

// Basic boot with user ID
amplitudeEngagement.boot("USER_ID")

// Advanced boot with options
let bootOptions = AmplitudeBootOptions(
    userId: "USER_ID",
    deviceId: "DEVICE_ID",
    userProperties: mapOf("key" to "value")
    integrations = arrayOf({ event: BaseEvent ->
        // Custom event handler
        // Dummy example here:
        println("event: ${event.eventType} properties: ${event.eventProperties}")
    })
)
amplitudeEngagement.boot(options: bootOptions)

Add your application to project settings

After installing the SDK, add your Android application to your Amplitude project settings so it appears as a platform option when you create guides and surveys.

To add your application:

1. Navigate to Settings > Projects in Amplitude.
2. Select your project.
3. Navigate to the Guides and Surveys tab.
4. In the App Management section, expand and click + Add App.
5. Select Android from the drop-down.

After you add your application, it appears as a platform option when you create or edit guides and surveys. This enables you to deliver guides and surveys to your Android app users.

Set a minimum SDK version (when needed)

Minimum SDK version is available for versions 3.0.0 and later. Use this setting as a safety control when you identify a critical issue in an older SDK release.

To configure a minimum SDK version:

1. Navigate to Settings > Projects in Amplitude.
2. Select your project.
3. Navigate to the Guides and Surveys tab.
4. In the App Management section, expand and click + Add App.
5. Select Android from the dropdown.
6. Enter a value in Minimum SDK version.

When you set this value, Guides and Surveys compares the configured minimum with the SDK version in each app build:

• If an app build uses an older SDK version, the SDK doesn't initialize in that build.
• If an app build uses the same or newer SDK version, the SDK initializes as expected.

This setting lets you stop guides and surveys on known problematic SDK versions without rolling back your application release.

Example usage of minimum SDK version

Suppose app version 120 uses Guides and Surveys SDK 3.0.2, and app version 121 uses Guides and Surveys SDK 3.1.0 with a bug fix. If you set Minimum SDK version to 3.1.0:

• App version 120 no longer loads Guides and Surveys.
• App version 121 continues to load Guides and Surveys.

Screen tracking and element targeting

Enable screen tracking

Required for screen-based targeting and the Time on Screen trigger. The screen string (for example, "HomeScreen") is compared with the string provided in the guide or survey page targeting section.

// Track screen views to trigger guides based on screens
amplitudeEngagement.screen("HomeScreen")

Enable element targeting

Pin and tooltip guides require the ability for the SDK to target specific elements on screen.

Jetpack Compose

Use Amplitude Engagement's .amplitudeView modifier to tag Jetpack Compose views. Pass your instance of AmplitudeEngagement as a parameter to .amplitudeView. Configure a CompositionLocalProvider and access it in your view hierarchy or pass your instance as a parameter to your composable views.

// Jetpack Compose Tagging

@Composable
fun MyView() {
    // Use your instance of Amplitude Engagement by creating a Composition context or passing as a param
    val engagement = LocalEngagement.current

    Box {
        Button(
            modifier = Modifier.amplitudeView(
                engagement, 
                tag = "my-button",
                onTrigger = {
                    // Optional code to run with tap element action
                }
            )
        )
    }
}

Non-Jetpack Compose

Guides and Surveys also supports non-Jetpack Compose views. The SDK uses the tag, contentDescription, or resourceName fields to check for a matching selector. You need to set only one of these.

Configure this in your existing layout XMLs or programmatically by setting the properties on the view instance.

<!-- in my_layout.xml -->
<LinearLayout>
    <!-- Set either contentDescription or tag to your desired selector -->
    <Button
        android:contentDescription="my-button"
        android:tag="my-button" />
</LinearLayout>

// Non Jetpack Compose Programmatic Tagging
val button = Button(this)

// Set the contentDescription
button.contentDescription = "my-button"
// Or set the tag
button.tag = "my-button"

Other SDK methods

This section describes additional methods available in the Android SDK for Amplitude Guides and Surveys, including:

• Managing themes: You can set the visual theme (light, dark, or auto) for guides and surveys using setThemeMode.
• Adding callbacks: You can register named callbacks and trigger them from guides or surveys using the Run callback action to execute custom app logic.
• Router configuration: You can customize how guides and surveys handle screen navigation by defining a router callback with setRouter, which lets you handle navigation logic in your app.
• Resetting guides/surveys: Use reset to move a guide or survey back to a specific step.
• Listing guides/surveys: Retrieve the full list of live guides and surveys and their current status using the list() method.

Manage themes

Configure the visual theme mode if your app supports light and dark modes.

// Set the theme mode
amplitudeEngagement.setThemeMode(ThemeMode.DARK) // Options: AUTO, LIGHT, DARK

Register a callback

Set the Run callback action on a guide or survey button to execute the callback.

engagement.addCallback(key: String, func: () -> Unit)

engagement.addCallback("show-alert") {
    this.runOnUiThread {
        android.app.AlertDialog.Builder(this)
            .setTitle("Callback")
            .setMessage("Callback has been executed!")
            .setPositiveButton("OK", null)
            .show()
    }
}

Router configuration

Configure how Guides and Surveys handles screen navigation.

engagement.setRouter { identifier ->
    // Your screen handling and navigation
}

Reset

Reset a guide or survey to a specific step.

amplitudeEngagement.reset(key = "GUIDE_KEY", stepIndex = 0)

List

Retrieve a list of all live guides and surveys along with their status.

val guidesAndSurveys = amplitudeEngagement.list()

Show

Display a specific guide or survey. Ignores any targeting rules and limits except for screen targeting.

amplitudeEngagement.show(key = "GUIDE_KEY")

Forward event

If you don't use the Amplitude Analytics Android SDK plugin (that is, you called boot directly), use forwardEvent to enable the On event tracked trigger in Guides and Surveys. Forwarded events aren't sent to Amplitude servers. The SDK uses them only for local trigger evaluation.

// Forward events from Amplitude to trigger guides
val event = BaseEvent()
amplitudeEngagement.forwardEvent(event)

Close all

Close all active guides and surveys.

amplitudeEngagement.closeAll()

Simulate Guides and Surveys for preview

Previewing guides and surveys direclty in your application allows you to experience what your users will. Previewing makes it much easier to iterate on copy, targeting rules, trigger logic, etc.

Locate the mobile URL scheme

To locate the URL scheme:

1. Navigate to Settings > Projects in Amplitude.
2. Select your project.
3. Navigate to the General tab.
4. Find the URL scheme (mobile) field.
5. Copy its value, for example, amp-abcdefgh12345678.

Add the URL scheme in Android Studio

Add the following intent filter to the main activity to your project's AndroidManifest.xml file:

<activity android:name=".MainActivity">
    <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- Add your URL scheme from Amplitude Dashboard here -->
    <!-- ex: android:scheme="amp-12345" -->
    <data android:scheme="<your-unique-scheme-id>" />
    </intent-filter>
</activity>

URL handling for preview links

// In your Activity
override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    amplitudeEngagement.handleLinkIntent(intent)
}

Known limitations

Targeting animated elements and elements inside moving containers

Pins and tooltips can't target views or elements that are:

• Animated or in an animated container (they move around the screen).
• In a container that can move based on user interaction.

Changelog

You can access the changelog here.