Guides and Surveys Android SDK | Amplitude Guides and Surveys

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) or higher
Kotlin 1.8.22 or newer
Amplitude Android-Kotlin SDK 1.0 or higher.

Install and initialize the SDK

Add the following depenedencies 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.+")
}

dependencies {
    // Amplitude Engagement SDK
    implementation("com.amplitude:amplitude-engagement-android:1.0+")
    
        // Amplitude Analytics SDK (required dependency)
implementation(&quot;com.amplitude:analytics-android:1.+&quot;)

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

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

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

Parameter	Type	Description
`apiKey`	`string`	Required. API key of the Amplitude project you want to use.
`initOptions.serverZone`	`EU` or `US`	Optional. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in EU data center. Default: `US`
`initOptions.logLevel`	`LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`.	Optional. Sets the log level. Default: `LogLevel.Warn`
`initOptions.locale`	`string`	Optional. Sets the locale for localization. Default: `undefined`. Not setting a language means the default language is used.

Boot the SDK

// Basic boot with user ID
amplitudeEngagement.boot(userId = "USER_ID")
 
// Advanced boot with options
val bootOptions = AmplitudeBootOptions(
    user = AmplitudeEndUser(
        userId = "USER_ID",
        deviceId = "DEVICE_ID",
        userProperties = mapOf("key" to "value")
    )
)
amplitudeEngagement.boot(bootOptions)

// Basic boot with user ID
amplitudeEngagement.boot(userId = "USER_ID")
// Advanced boot with options
val bootOptions = AmplitudeBootOptions(
user = AmplitudeEndUser(
userId = "USER_ID",
deviceId = "DEVICE_ID",
userProperties = mapOf("key" to "value")
)
)
amplitudeEngagement.boot(bootOptions)

Enable screen tracking (optional)

Required for screen targeting and the Time on Screen trigger.

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

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

Manage themes

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

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

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

Register a callback

Reset

Reset a guide or survey to a specific step.

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

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

Parameter	Type	Description
`key`	`string`	Required. The guide or survey's key.
`stepIndex`	`number`	Required. The zero-based index of the step to reset to. Defaults to the initial step.

List

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

val guidesAndSurveys = amplitudeEngagement.list()

val guidesAndSurveys = amplitudeEngagement.list()

Show

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

amplitudeEngagement.show(key = "GUIDE_KEY")

amplitudeEngagement.show(key = "GUIDE_KEY")

Parameter	Type	Description
`key`	`string`	Required. The guide or survey's 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)

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

Close all

Close all active guides and surveys.

amplitudeEngagement.closeAll()

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.

Locate the mobile URL scheme

In Amplitude, navigate to your Project's settings.

On the General tab, locate the URL scheme (mobile) field. 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>

<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)
}

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