Experiment React Native SDK

Official documentation for Amplitude Experiment's Client-side React Native SDK.

Install

Install the Experiment JavaScript Client SDK. This library depends on @react-native-async-storage/async-storage which you also need to install.

1npm install @amplitude/experiment-react-native-client
2npm install @react-native-async-storage/async-storage

1yarn add @amplitude/experiment-react-native-client
2yarn add @react-native-async-storage/async-storage

1expo install @amplitude/experiment-react-native-client
2expo install @react-native-async-storage/async-storage

You need to install the native modules to run the SDK on iOS.

1cd ios
2pod install

 1import { Experiment } from '@amplitude/experiment-react-native-client';
 2 
 3// (1) Initialize the experiment client with Amplitude Analytics.
 4const experiment = Experiment.initializeWithAmplitudeAnalytics(
 5    'DEPLOYMENT_KEY'
 6);
 7 
 8// (2) Fetch variants and await the promise result.
 9await experiment.fetch();
10 
11// (3) Lookup a flag's variant.
12const variant = experiment.variant('FLAG_KEY');
13if (variant.value === 'on') {
14    // Flag is on
15} else {
16    // Flag is off
17}

 1import { Experiment } from '@amplitude/experiment-react-native-client';
 2 
 3// (1) Initialize the experiment client with Amplitude Analytics and
 4// implement an exposure tracking provider.
 5const experiment = Experiment.initialize(
 6   'DEPLOYMENT_KEY',
 7   {
 8       exposureTrackingProvider: {
 9           track: (exposure) => {
10               // TODO: Implement exposure tracking
11               // analytics.track('$exposure', exposure)
12           }
13       }
14   }
15);
16 
17// (2) Fetch variants with the user and await the promise result.
18const user = {
19   user_id: 'user@company.com',
20   device_id: 'abcdefg',
21   user_properties: {
22       premium: true,
23   },
24}
25await experiment.start(user);
26 
27// (3) Lookup a flag's variant.
28const variant = experiment.variant('FLAG_KEY');
29if (variant.value === 'on') {
30   // Flag is on
31} else {
32   // Flag is off
33}

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.

1initializeWithAmplitudeAnalytics(apiKey: string, config?: ExperimentConfig): ExperimentClient

1initialize(apiKey: string, config?: ExperimentConfig): ExperimentClient

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.

1import { Experiment } from '@amplitude/experiment-js-client';
2 
3const experiment = initializeWithAmplitudeAnalytics('DEPLOYMENT_KEY');

 1import { Experiment } from '@amplitude/experiment-js-client';
 2 
 3const experiment = Experiment.initialize(
 4    'DEPLOYMENT_KEY',
 5    {
 6        exposureTrackingProvider: {
 7            track: (exposure) => {
 8                // TODO: Implement exposure tracking
 9                // analytics.track('$exposure', exposure)
10            }
11        }
12    }
13);

Configuration

SDK client configuration occurs during initialization.

Integrations

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

1import * as amplitude from '@amplitude/analytics-browser';
2import { Experiment } from '@amplitude/experiment-js-client';
3 
4amplitude.init('API_KEY');
5const experiment = Experiment.initializeWithAmplitudeAnalytics('DEPLOYMENT_KEY'); 

1analytics.ready(() => {
2    const experiment =  Experiment.initialize('DEPLOYMENT_KEY', {
3        exposureTrackingProvider: {
4            track: (exposure) => {
5                analytics.track('$exposure', exposure)
6            }
7        }
8    });
9});

1await experiment.fetch({
2    user_id: analytics.user().id(),
3    device_id: analytics.user().analyticsId(),
4});

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.

1fetch(user?: ExperimentUser): Promise<Client>

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, should wait for the fetch request to return a result before rendering the user experience to avoid the interface "flickering".

1const user = {
2    user_id: 'user@company.com',
3    device_id: 'abcdefg',
4    user_properties: {
5        'premium': true,
6    },
7};
8await experiment.fetch(user);

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

1await experiment.fetch();

If fetch() times out (default 10 seconds) or fails for any reason, the SDK client will return and retry in the background with back-off. You may configure the timeout or disable retries in the configuration options when the SDK client is initialized.

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 promise resolves.

1start(user?: ExperimentUser): Promise<void>

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

Set fetchOnStart in the SDK configuration to set the behavior of start() to improve the performance 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 promise separately.

1await experiment.start();

1const user = {
2    user_id: 'user@company.com',
3    device_id: 'abcdefg',
4    user_properties: {
5        premium: true
6    }
7};
8await experiment.start(user);

If the client is bootstrapped with initialVariants or initialFlags and doesn't need to await the results of start(), call and await cacheReady() to ensure variants and flags have been loaded from async storage.

Variant

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

1variant(key: string, fallback?: string | Variant): Variant

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

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

1const variant = experiment.variant('<FLAG_KEY>');
2if (variant.value === 'on') {
3    const payload = variant.payload;
4}

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.

1const variant = experiment.variant('<FLAG_KEY>', { value: 'control' });
2if (variant === 'control') {
3    // Control
4} else if (variant === 'treatment') {
5    // Treatment
6}

All

Access all variants stored by the SDK client.

1all(): Variants

Clear

Clear all variants in the cache and storage.

1clear(): void

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

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.

1exposure(key: string): void

 1const variant = experiment.variant('<FLAG_KEY>');
 2 
 3// Do other things...
 4 
 5experiment.exposure('<FLAG_KEY>');
 6if (variant === 'control') {
 7    // Control
 8} else if (variant === '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  getUser(): ExperimentUser;
3}

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

1const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
2    userProvider: new CustomUserProvider(),
3});

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.

1export interface ExposureTrackingProvider {
2  track(exposure: Exposure): void;
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.

1const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
2    exposureTrackingProvider: new CustomExposureTrackingProvider(),
3});

Bootstrapping

You may want to bootstrap the experiment client with an initial set of flags and variants when variants are obtained from an external source (for example, not from calling fetch() on the SDK client). Use cases include local evaluation, server-side rendering, or integration testing on specific variants.

To bootstrap the client, set the flags and variants in the initialVariants configuration object, then set the source to Source.InitialVariants so that the SDK client prefers the bootstrapped variants over any previously fetched & stored variants for the same flags.

1const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
2    initialVariants: { /* Flags and variants */ },
3    source: Source.InitialVariants,
4});