Experiment Android SDK

Official documentation for Amplitude Experiment's Client-side Android SDK implementation.

Install

Add to the dependencies in your Android project's build.gradle file.

1dependencies {
2  implementation 'com.amplitude:experiment-android-client:<VERSION>'
3}

 1class MyApplication : Application() {
 2 
 3    override fun onCreate() {
 4        super.onCreate()
 5 
 6        // (1) Initialize the experiment client
 7        val client = Experiment.initializeWithAmplitudeAnalytics(
 8            this, "DEPLOYMENT_KEY", ExperimentConfig()
 9        )
10 
11        // (2) Fetch variants for a user
12        try {
13            client.start().get()
14        } catch (e: Exception) {
15            e.printStackTrace()
16        }
17 
18        // (3) Lookup a flag's variant
19        val variant = client.variant("<FLAG_KEY>")
20        if (variant.value == "on") {
21            // Flag is on
22        } else {
23            // Flag is off
24        }
25    }
26}

 1class MyApplication : Application() {
 2 
 3   override fun onCreate() {
 4       super.onCreate()
 5 
 6       // (1) Initialize the experiment client
 7       val client = Experiment.initialize(this, "DEPLOYMENT_KEY", ExperimentConfig.builder()
 8           .exposureTrackingProvider(object : ExposureTrackingProvider {
 9               override fun track(exposure: Exposure) {
10                   // TODO: Implement exposure tracking
11                   // Analytics.with(context).track(
12                   //     "\$exposure",
13                   //     Properties()
14                   //         .putValue("flag_key", exposure.flagKey)
15                   //         .putValue("variant", exposure.variant)
16                   //         .putValue("experiment_key", exposure.experimentKey));
17                   // )
18               }
19           }).build()
20       )
21 
22       // (2) Fetch variants for a user
23       val user = ExperimentUser.builder()
24           .userId("user@company.com")
25           .deviceId("abcdefg")
26           .userProperty("premium", true)
27           .build()
28       try {
29           client.start().get()
30       } catch (e: Exception) {
31           e.printStackTrace()
32       }
33 
34       // (3) Lookup a flag's variant
35       val variant = client.variant("<FLAG_KEY>")
36       if (variant.value == "on") {
37           // Flag is on
38       } else {
39           // Flag is off
40       }
41   }
42}

Core functions

The following functions make up the core of the Experiment client-side SDK.

Initialize

The SDK client should be initialized in your application on startup. The deployment key argument passed into the apiKey parameter must live within the same project that you are sending analytics events to.

1fun initializeWithAmplitudeAnalytics(
2    application: Application, apiKey: String, config: ExperimentConfig
3)

1fun initialize(application: Application, apiKey: String, config: ExperimentConfig)

The initializer returns a singleton instance, so subsequent initializations for the same instance name will always return the initial instance. To create multiple instances, use the instanceName configuration.

1val experiment = Experiment.initializeWithAmplitudeAnalytics(
2    context, "DEPLOYMENT_KEY", ExperimentConfig()
3)

1val experiment = Experiment.initialize(context, "DEPLOYMENT_KEY", ExperimentConfig())

Configuration

SDK client configuration occurs during initialization.

Integrations

If you use either Amplitude or Segment Analytics SDKs to track events into Amplitude, set up an integration on initialization. Integrations automatically implement provider interfaces to enable a more streamlined developer experience by making it easier to manage user identity and track exposures events.

1Amplitude.getInstance().init("API_KEY");
2ExperimentClient experiment = Experiment.initializeWithAmplitudeAnalytics( 
3    context, "DEPLOYMENT_KEY", new ExperimentConfig());

1Amplitude.getInstance().init("API_KEY")
2val experiment = Experiment.initializeWithAmplitudeAnalytics( 
3    context,
4    "DEPLOYMENT_KEY",
5    ExperimentConfig(),
6)

 1class SegmentExposureTrackingProvider implements ExposureTrackingProvider {
 2    private Analytics analytics;
 3    public SegmentExposureTrackingProvider(Analytics analytics) {
 4        this.analytics = analytics;
 5    }
 6    @Override
 7    public void track(Exposure exposure) {
 8        analytics.track(
 9                "$exposure",
10                new Properties()
11                    .putValue("flag_key", exposure.flagKey)
12                    .putValue("variant", exposure.variant)
13                    .putValue("experiment_key", exposure.experimentKey));
14    }
15}

 1class SegmentExposureTrackingProvider(
 2    private val analytics: Analytics
 3): ExposureTrackingProvider {
 4 
 5    override fun track(exposure: Exposure) {
 6        analytics.track(
 7            "\$exposure",
 8            Properties()
 9                .putValue("flag_key", exposure.flagKey)
10                .putValue("variant", exposure.variant)
11                .putValue("experiment_key", exposure.experimentKey)
12        )
13    }
14}

1Analytics analytics = // Initialize segment analytics
2ExperimentConfig config = ExperimentConfig.builder()
3    .exposureTrackingProvider(new SegmentExposureTrackingProvider(analytics))
4    .build();
5ExperimentClient experiment = Experiment.initialize(context, "DEPLOYMENT_KEY", config);

1val analytics = // Initialize segment analytics
2val config = ExperimentConfig.builder()
3    .exposureTrackingProvider(SegmentExposureTrackingProvider(analytics))
4    .build()
5val experiment = Experiment.initialize(context, "DEPLOYMENT_KEY", config)

 1String userId = analytics.getAnalyticsContext().traits().userId();
 2String deviceId = analytics.getAnalyticsContext().traits().anonymousId();
 3try {
 4    ExperimentUser user = ExperimentUser.builder()
 5        .userId(userId)
 6        .deviceId(deviceId)
 7        .build();
 8    experiment.start(user).get();
 9} catch (Exception e) {
10    e.printStackTrace();
11}

 1val userId = analytics.analyticsContext.traits().userId()
 2val deviceId = analytics.analyticsContext.traits().anonymousId()
 3try {
 4    val user = ExperimentUser.builder()
 5        .userId(userId)
 6        .deviceId(deviceId)
 7        .build()
 8    experiment.start(user).get()
 9} catch (e: Exception) {
10    e.printStackTrace()
11}

Start

Start the Experiment SDK to get flag configurations from the server and fetch remote evaluation variants for the user. The SDK is ready once the returned future resolves.

1fun start(user: ExperimentUser? = null): Future<ExperimentClient>

Call start() when your application is initializing, after user information is available to use to evaluate or fetch variants. The returned future resolves after loading local evaluation flag configurations and fetching remote evaluation variants.

Configure the behavior of start() by setting fetchOnStart in the SDK configuration on initialization to improve performance based on the needs of your application.

• If your application never relies on remote evaluation, set fetchOnStart to false to avoid increased startup latency caused by remote evaluation.
• If your application relies on remote evaluation, but not right at startup, you may set fetchOnStart to false and call fetch() and await the future separately.

1try {
2    experiment.start().get();
3} catch (e: Exception) {
4    e.printStackTrace();
5}

1ExperimentUser user = ExperimentUser.builder()
2    .userId("user@company.com")
3    .userProperty("premium", true)
4    .build();
5try {
6    experiment.start(user).get();
7} catch (e: Exception) {
8    e.printStackTrace();
9}

Fetch

Fetches variants for a user and store the results in the client for fast access. This function remote evaluates the user for flags associated with the deployment used to initialize the SDK client.

1fun fetch(user: ExperimentUser? = null, options: FetchOptions? = null): Future<ExperimentClient>

Amplitude Experiment recommends calling fetch() during application start up so that the user gets the most up-to-date variants for the application session. Furthermore, you'll need to wait for the fetch request to return a result before rendering the user experience to avoid the interface "flickering".

1try {
2    ExperimentUser user = ExperimentUser.builder()
3        .userId("user@company.com")
4        .userProperty("premium", true)
5        .build();
6    experiment.fetch(user).get();
7} catch (Exception e) {
8    e.printStackTrace();
9}

1try {
2    val user = ExperimentUser.builder()
3        .userId("user@company.com")
4        .userProperty("premium", true)
5        .build()
6    experiment.fetch(user).get()
7} catch (e: Exception) {
8    e.printStackTrace()
9}

If you're using an integration or a custom user provider then you can fetch without inputting the user.

1experiment.fetch(null);

1experiment.fetch()

Variant

Access a variant for a flag or experiment from the SDK client's local store.

1fun variant(key: String, fallback: Variant? = null): Variant

When determining which variant a user has been bucketed into, you'll want to compare the variant value to a well-known string.

1Variant variant = client.variant("<FLAG_KEY>");
2if (variant.is("on")) {
3    // Flag is on
4} else {
5    // Flag is off
6}

1Variant variant = client.variant("<FLAG_KEY>");
2if (variant.value == "on") {
3    // Flag is on
4} else {
5    // Flag is off
6}

1Variant variant = experiment.variant("<FLAG_KEY>");
2if (variant.is("on") && variant.payload != null) {
3    try {
4        String value = ((JSONObject) variant.payload).getString("key");
5    } catch (Exception e) {
6        e.printStackTrace();
7    }
8}

1val variant = experiment.variant("<FLAG_KEY>")
2if (variant.value == "on") {
3    try {
4        val value = (variant.payload as JSONObject).getString("key")
5    } catch (e: Exception) {
6        e.printStackTrace()
7    }
8}

A null variant value means that the user hasn't been bucketed into a variant. You may use the built in fallback parameter to provide a variant to return if the store doesn't contain a variant for the given flag key.

1Variant variant = experiment.variant("<FLAG_KEY>", new Variant("control"));
2if (variant.is("control")) {
3    // Control
4} else if (variant.is("treatment")) {
5    // Treatment
6}

1val variant = experiment.variant("<FLAG_KEY>", Variant("control"))
2if (variant.value == "control") {
3    // Control
4} else if (variant.value == "treatment") {
5    // Treatment
6}

All

Access all variants stored by the SDK client.

1fun all(): Map<String, Variant>

1experiment.all();

1experiment.all()

Clear

Clear all variants in the cache and storage.

1fun clear()

You can call clear after user logout to clear the variants in cache and storage.

1experiment.clear();

1experiment.clear()

Exposure

Manually track an exposure event for the current variant of the given flag key through configured integration or custom exposure tracking provider. Generally used in conjunction with setting the automaticExposureTracking configuration optional to false.

1fun exposure(key: String)

 1Variant variant = experiment.variant("<FLAG_KEY>");
 2 
 3// Do other things...
 4 
 5experiment.exposure("<FLAG_KEY>");
 6if (variant.is("control")) {
 7    // Control
 8} else if (variant.is("treatment")) {
 9    // Treatment
10}

 1val variant = experiment.variant("<FLAG_KEY>")
 2 
 3// Do other things...
 4 
 5experiment.exposure("<FLAG_KEY>")
 6if (variant.value == "control") {
 7    // Control
 8} else if (variant.value == "treatment") {
 9    // Treatment
10}

Providers

Provider implementations enable a more streamlined developer experience by making it easier to manage user identity and track exposures events.

User provider

The user provider is used by the SDK client to access the most up-to-date user information only when it's needed (for example, when fetch() is called). This provider is optional, but helps if you have a user information store already set up in your application. This way, you don't need to manage two separate user info stores in parallel, which may result in a divergent user state if the application user store is updated and experiment isn't (or vice versa).

1interface ExperimentUserProvider {
2    fun getUser(): ExperimentUser
3}

To use your custom user provider, set the userProvider configuration option with an instance of your custom implementation on SDK initialization.

1ExperimentConfig config = ExperimentConfig.builder()
2    .userProvider(new CustomUserProvider())
3    .build();
4ExperimentClient experiment = Experiment.initialize(
5    context, "<DEPLOYMENT_KEY>", config);

1val config = ExperimentConfig.builder()
2    .userProvider(CustomUserProvider())
3    .build()
4val experiment = Experiment.initialize(context, "<DEPLOYMENT_KEY>", config)

Exposure tracking provider

Implementing an exposure tracking provider is highly recommended. Exposure tracking increases the accuracy and reliability of experiment results and improves visibility into which flags and experiments a user is exposed to.

1interface ExposureTrackingProvider {
2    fun track(exposure: Exposure)
3}

The implementation of track() should track an event of type $exposure (a.k.a name) with two event properties, flag_key and variant, corresponding to the two fields on the Exposure object argument. Finally, the event tracked must eventually end up in Amplitude Analytics for the same project that the [deployment] used to initialize the SDK client lives within, and for the same user that variants were fetched for.

To use your custom user provider, set the exposureTrackingProvider configuration option with an instance of your custom implementation on SDK initialization.

1ExperimentConfig config = ExperimentConfig.builder()
2    .exposureTrackingProvider(new CustomExposureTrackingProvider())
3    .build();
4ExperimentClient experiment = Experiment.initialize(
5    context, "<DEPLOYMENT_KEY>", config);

1val config = ExperimentConfig.builder()
2    .exposureTrackingProvider(CustomExposureTrackingProvider())
3    .build()
4val experiment = Experiment.initialize(context, "<DEPLOYMENT_KEY>", config)