Products

Developers

FAQ

Search docsFull width

On this page

Install
Initialize
Configuration
Integrations
Fetch
Start
Variant
All
Clear
Exposure
Providers
User provider
Exposure tracking provider
Bootstrapping
HTTP client
Custom logging
Log levels
Custom logger
Debug flag (deprecated)

SDKs
/
Experiment
/
Experiment React Native SDK

Experiment React Native SDK

npmv1.8.0

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.

Web and Expo support

Use this SDK for react-native apps built for web or built using Expo (Expo Go not yet supported).

npmyarnexpo

Copy

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

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

bash

Copy

cd ios
pod install

Quick start

The right way to initialize the Experiment SDK depends on whether you use an Amplitude SDK for analytics or a third party (for example, Segment).

AmplitudeThird party

Initialize the experiment client
Fetch variants
Access a flag's variant

Copy

import { Experiment } from '@amplitude/experiment-react-native-client';

// (1) Initialize the experiment client with Amplitude Analytics.
const experiment = Experiment.initializeWithAmplitudeAnalytics(
    'DEPLOYMENT_KEY'
);

// (2) Fetch variants and await the promise result.
await experiment.fetch();

// (3) Lookup a flag's variant.
const variant = experiment.variant('FLAG_KEY');
if (variant.value === 'on') {
    // Flag is on
} else {
    // Flag is off
}

Initialize

Initialize the SDK client in your application on startup. The deployment key argument you pass to the apiKey parameter must live within the same project that you are sending analytics events to.

AmplitudeThird party

Copy

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

Parameter	Requirement	Description
`apiKey`	required	The deployment key that authorizes fetch requests and determines which flags to evaluate for the user.
`config`	optional	The client configuration used to customize SDK client behavior.

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

AmplitudeThird party

Copy

import { Experiment } from '@amplitude/experiment-js-client';

const experiment = initializeWithAmplitudeAnalytics('DEPLOYMENT_KEY');

Instance name

If you're using a custom instance name for analytics, you need to set the same value in the instanceName configuration option in the experiment SDK, or visa versa.

Configuration

SDK client configuration occurs during initialization.

Name	Description	Default Value
`debug`	Deprecated. When `true`, sets `logLevel` to `Debug`. Use `logLevel` instead.	`false`
`logLevel`	The minimum log level to output. The SDK ignores messages below this level. Options: `Disable`, `Error`, `Warn`, `Info`, `Debug`, `Verbose`. Go to Custom logging for details.	`LogLevel.Error`
`loggerProvider`	Custom logger implementation. Must implement the `Logger` interface. Go to Custom logging for details.	`null` (uses default ConsoleLogger)
`fallbackVariant`	The default variant to fall back if a variant for the provided key doesn't exist.	`{}`
`initialVariants`	An initial set of variants to access. This field helps bootstrap the client SDK with values rendered by the server using server-side rendering (SSR).	`{}`
`source`	The primary source of variants. Set the value to `Source.InitialVariants` and configured `initialVariants` to bootstrap the SDK for SSR or testing purposes.	`Source.LocalStorage`
`serverZone`	Select the Amplitude data center to get flags and variants from, `us` or `eu`.	`us`
`serverUrl`	The host to fetch remote evaluation variants from. For hitting the EU data center, use `serverZone`.	`https://api.lab.amplitude.com`
`flagsServerUrl`	The host to fetch local evaluation flags from. For hitting the EU data center, use `serverZone`.	`https://flag.lab.amplitude.com`
`fetchTimeoutMillis`	The timeout for fetching variants in milliseconds.	`10000`
`retryFetchOnFailure`	Whether to retry variant fetches in the background if the request doesn't succeed.	`true`
`automaticExposureTracking`	If true, calling`variant()`tracks an exposure event through the configured`exposureTrackingProvider`. If no exposure tracking provider is set, this configuration option does nothing.	`true`
`fetchOnStart`	If true or undefined, always fetch remote evaluation variants on start. If false, never fetch on start.	`true`
`pollOnStart`	Poll for local evaluation flag configuration updates every minute on start.	`true`
`automaticFetchOnAmplitudeIdentityChange`	Only matters if you use the`initializeWithAmplitudeAnalytics`initialization function to integrate with the Amplitude Analytics SDK. If`true`any change to the user ID, device ID or user properties from analytics triggers the experiment SDK to fetch variants and update its cache.	`false`
`userProvider`	An interface used to provide the user object to`fetch()`when called.	`null`
`exposureTrackingProvider`	Implement and configure this interface to track exposure events through the experiment SDK, either automatically or explicitly.	`null`
`instanceName`	Custom instance name for experiment SDK instance. The value of this field is case-sensitive.	`null`
`initialFlags`	A JSON string representing an initial set of flag configurations to use for local evaluation.	`undefined`
`httpClient`	(Advanced) Use your own HTTP client implementation to handle network requests made by the SDK.	Default HTTP client

EU data center

If you're using Amplitude's EU data center, configure the serverZone option on initialization to eu.

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.

Amplitude integration

Segment integration

Fetch

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

Copy

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

Parameter	Requirement	Description
`user`	optional	Explicit user information to pass with the request to evaluate. The SDK merges this user information with user information provided from integrations through the user provider, preferring properties passed explicitly to `fetch()` over provided properties.

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

Copy

const user = {
    user_id: 'user@company.com',
    device_id: 'abcdefg',
    user_properties: {
        'premium': true,
    },
};
await experiment.fetch(user);

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

Copy

await experiment.fetch();

Fetch when user identity changes

If you want the most up-to-date variants for the user, it's recommended that you call fetch() whenever the user state changes in a meaningful way. For example, if the user logs in and receives a user ID, or has a user property set which may affect flag or experiment targeting rules.

In the case of user properties, Amplitude recommends passing new user properties explicitly to fetch() instead of relying on user enrichment before remote evaluation. Remote user-property sync through a separate system has no timing guarantees for fetch(), which can create a race condition.

If fetch() times out (default 10 seconds) or fails for any reason, the SDK client returns and retries in the background with back-off. You may configure the timeout or disable retries in the configuration options during SDK client initialization.

Account-level bucketing and analysis (v1.1.0+)

Start

Fetch vs start

Use start if you're using client-side local evaluation. If you're only using remote evaluation, call fetch instead of start.

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

Copy

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

| Parameter | Requirement | Description | | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | user | optional | Explicit user information to pass with the request to fetch variants. This user information merges with user information from any integrations through the user provider, and prefers properties passed explicitly to fetch() over provided properties. Also sets the user in the SDK for reuse. | undefined |Call start() when your application is initializing, after user information is available to evaluate or fetch variants. The 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.

AmplitudeThird party

Copy

await experiment.start();

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 async storage has loaded variants and flags.

Variant

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

Automatic exposure tracking

When you use an integration or set a custom exposure tracking provider, variant() automatically tracks an exposure event through the tracking provider. To disable this functionality, configure automaticExposureTracking to be false, and track exposures manually using exposure().

Copy

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

Parameter	Requirement	Description
`key`	required	The flag key to identify the flag or experiment to access the variant for.
`fallback`	optional	The value to return if no variant was found for the given `flagKey`.

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

Copy

const variant = experiment.variant('<FLAG_KEY>');
if (variant.value === 'on') {
    // Flag is on
} else {
    // Flag is off
}

Access a variant's payload

A variant may also be configured with a dynamic payload of arbitrary data. Access the payload field from the variant object after checking the variant's value.

Copy

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

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.

Copy

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

All

Access all variants stored by the SDK client.

Copy

all(): Variants

Clear

Clear all variants in the cache and storage.

Copy

clear(): void

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

Copy

experiment.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.

Copy

exposure(key: string): void

Parameter	Requirement	Description
`key`	required	The flag key to identify the flag or experiment variant to track an exposure event for.

Copy

const variant = experiment.variant('<FLAG_KEY>');

// Do other things...

experiment.exposure('<FLAG_KEY>');
if (variant === 'control') {
    // Control
} else if (variant === 'treatment') {
    // Treatment
}

Providers

Integrations

If you use Amplitude or Segment analytics SDKs along side the Experiment Client SDK, Amplitude recommends you use an integration instead of implementing custom providers.

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

User provider

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

Copy

interface ExperimentUserProvider {
  getUser(): ExperimentUser;
}

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

Copy

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

Exposure tracking provider

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

Copy

export interface ExposureTrackingProvider {
  track(exposure: Exposure): void;
}

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.

Copy

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

Bootstrapping

You may want to bootstrap the experiment client with an initial set of flags and variants when variants come 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.

Copy

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

HTTP client

You can provide a custom HTTP client implementation to handle network requests made by the SDK. This is useful for environments with specific networking requirements or when you need to customize request handling.

Copy

export interface SimpleResponse {
  status: number;
  body: string;
}

export interface HttpClient {
  request(
    requestUrl: string,
    method: string,
    headers: Record<string, string>,
    data: string,
    timeoutMillis?: number,
  ): Promise<SimpleResponse>;
}

To use your custom HTTP client, set the httpClient configuration option with an instance of your implementation on SDK initialization.

Copy

const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    httpClient: new CustomHttpClient(),
});

Custom logging

Control log verbosity with the logLevel configuration or implement the Logger interface to use your own logging solution.

Log levels

LogLevel.Disable - No logging.
LogLevel.Error - Errors only (default).
LogLevel.Warn - Errors and warnings.
LogLevel.Info - Errors, warnings, and informational messages.
LogLevel.Debug - Errors, warnings, info, and debug messages.
LogLevel.Verbose - All messages including verbose details.

Copy

import { Experiment, LogLevel } from '@amplitude/experiment-react-native-client';

// Only log errors
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  logLevel: LogLevel.Error
});

// Log errors and warnings
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  logLevel: LogLevel.Warn
});

// Log everything (verbose)
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  logLevel: LogLevel.Verbose
});

Custom logger

Implement the Logger interface to use your own logging solution.

Copy

import { Experiment, Logger, LogLevel } from '@amplitude/experiment-react-native-client';

// Implement the Logger interface
class CustomLogger implements Logger {
  error(message, ...optionalParams) {
    // Send errors to your logging service
    myLoggingService.error(message, ...optionalParams);
  }

  warn(message, ...optionalParams) {
    myLoggingService.warn(message, ...optionalParams);
  }

  info(message, ...optionalParams) {
    myLoggingService.info(message, ...optionalParams);
  }

  debug(message, ...optionalParams) {
    myLoggingService.debug(message, ...optionalParams);
  }

  verbose(message, ...optionalParams) {
    myLoggingService.verbose(message, ...optionalParams);
  }
}

// Initialize with custom logger
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  loggerProvider: new CustomLogger(),
  logLevel: LogLevel.Warn
});

Debug flag (deprecated)

The debug configuration flag is deprecated. Use logLevel instead.

Copy

// Deprecated: Sets logLevel to Debug
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  debug: true
});

// Preferred: Use logLevel instead
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  logLevel: LogLevel.Debug
});

Was this helpful?

On this page

Install
Initialize
- Configuration
- Integrations
Fetch
Start
Variant
All
Clear
Exposure
Providers
- User provider
- Exposure tracking provider
Bootstrapping
HTTP client
Custom logging