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+
• Amplitude Android-Kotlin SDK 1.0+

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 Android-Kotlin 1.0+

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

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

    // 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())

Configuration options

Not using Amplitude Android-Kotlin 1.0+

In this case, installation is very similar to above; however, you need to manually call .boot.

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

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

    // 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())

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 General tab.
4. In the Platform section, click + Add Platform.
5. Select Android from the platform list.
6. Enter your application details:
   • App name: Your app's display name
   • Package name: Your Android package identifier (for example, com.example.myapp)
7. Click Save.

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

Screen tracking and element targeting

Enable screen tracking

Required for screen-based targeting and the Time on Screen trigger. The screen string (eg "HomeScreen" in the example below) 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>
    <Button
        <!-- Set either contentDescription or tag to your desired selector -->
        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"

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

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 plugin, but want to trigger Guides using events, call forwardEvent with any events want to use as triggers.

// 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

To use preview mode to test a guide or survey in your app, configure a custom URL scheme.

Add your mobile app to project settings

Before you can use preview mode, add your Android app to your project settings in Amplitude:

1. In Amplitude, navigate to Settings > Organization Settings > Projects.
2. Select your project.
3. Click the Guides and Surveys tab.
4. In the App Management section, click Add App.
5. Enter your Android app's package name (for example, com.example.myapp).
6. Click Save.

After you add your app, Amplitude generates a unique URL scheme for mobile preview.

Locate the mobile URL scheme

After adding your app to project settings, locate the URL scheme:

1. In the Guides and Surveys tab of your project settings, find the URL scheme (mobile) field.
2. Copy its value, for example, amp-abc123.

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.handlePreviewLinkIntent(intent)
}

Changelog

You can access the changelog here.