Experiment React Native SDK (Legacy)

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

Install

Install the Experiment JavaScript Client SDK.

1npm install --save @amplitude/experiment-react-native-client

1yarn add @amplitude/experiment-react-native-client

 1// (1) Initialize the experiment client
 2await Experiment.initialize('<DEPLOYMENT_KEY>');
 3 
 4// (2) Fetch variants for a user
 5const user = {
 6    user_id: 'user@company.com',
 7    device_id: 'abcdefg',
 8    user_properties: {
 9        'premium': true,
10    },
11};
12await Experiment.fetch(user);
13 
14// (3) Lookup a flag's variant
15const variant = await Experiment.variant('<FLAG_KEY>');
16if (variant.value === 'on') {
17    // Flag is on
18} else {
19    // Flag is off
20}

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.

1initialize(apiKey: string, config?: ExperimentConfig): Promise<boolean>

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.

1const experiment = await Experiment.initialize('<DEPLOYMENT_KEY>');

Integrations

If you use either Amplitude or Segment Analytics SDKs to track events into Amplitude, you'll want to 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.

1await Amplitude.getInstance().init('<API_KEY>');
2await Experiment.initializeWithAmplitudeAnalytics('<DEPLOYMENT_KEY>');

Configuration

The SDK client can be configured once on initialization.

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

Amplitude 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 in order 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();

Variant

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

1variant(key: string): Promise<Variant>

1variantWithFallback(key: string, fallback: Variant): Promise<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 = await Experiment.variant('<FLAG_KEY>');
2if (variant.value === 'on') {
3    // Flag is on
4} else {
5    // Flag is off
6}

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

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

1const variant = await Experiment.variantWithFallback('<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(): Promise<Variants>

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): Promise<boolean>

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