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. {% callout type="info" heading="Web and Expo support" %} Use this SDK for react-native apps built for web or built using [Expo](https://expo.dev/) (Expo Go not yet supported). {% /callout %} {% code-group %} ```bash npm npm install @amplitude/experiment-react-native-client npm install @react-native-async-storage/async-storage ``` ```bash yarn yarn add @amplitude/experiment-react-native-client yarn add @react-native-async-storage/async-storage ``` ```bash expo expo install @amplitude/experiment-react-native-client expo install @react-native-async-storage/async-storage ``` {% /code-group %} You need to install the native modules to run the SDK on iOS. ```bash cd ios pod install ``` {% callout type="tip" heading="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). {% tabs tabs="Amplitude, Third party" %} {% tab name="Amplitude" %} 1. [Initialize the experiment client](#initialize) 2. [Fetch variants](#fetch) 3. [Access a flag's variant](#variant) ```js 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 } ``` {% /tab %} {% tab name="Third party" %} 1. [Initialize the experiment client](#initialize) 2. [Fetch variants for a user](#fetch) 3. [Access a flag's variant](#variant) ```js import { Experiment } from '@amplitude/experiment-react-native-client'; // (1) Initialize the experiment client with Amplitude Analytics and // implement an exposure tracking provider. const experiment = Experiment.initialize( 'DEPLOYMENT_KEY', { exposureTrackingProvider: { track: (exposure) => { // TODO: Implement exposure tracking // analytics.track('$exposure', exposure) } } } ); // (2) Fetch variants with the user and await the promise result. const user = { user_id: 'user@company.com', device_id: 'abcdefg', user_properties: { premium: true, }, } await experiment.start(user); // (3) Lookup a flag's variant. const variant = experiment.variant('FLAG_KEY'); if (variant.value === 'on') { // Flag is on } else { // Flag is off } ``` {% /tab %} {% /tabs %} {% /callout %} ## Initialize Initialize the SDK client in your application on startup. The [deployment key](/docs/feature-experiment/data-model#deployments) argument you pass to the `apiKey` parameter must live within the same project that you are sending analytics events to. {% code-group %} ```js Amplitude initializeWithAmplitudeAnalytics(apiKey: string, config?: ExperimentConfig): ExperimentClient ``` ```js Third party initialize(apiKey: string, config?: ExperimentConfig): ExperimentClient ``` {% /code-group %} | Parameter | Requirement | Description | | --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` | required | The [deployment key](/docs/feature-experiment/data-model#deployments) that authorizes fetch requests and determines which flags to evaluate for the user. | | `config` | optional | The client [configuration](#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](#configuration). {% tabs tabs="Amplitude, Third party" %} {% tab name="Amplitude" %} ```js import { Experiment } from '@amplitude/experiment-js-client'; const experiment = initializeWithAmplitudeAnalytics('DEPLOYMENT_KEY'); ``` {% callout type="note" heading="Instance name" %} If you're using a custom instance name for analytics, you need to set the same value in the `instanceName` [configuration option](#configuration) in the experiment SDK, or visa versa. {% /callout %} {% /tab %} {% tab name="Third party" %} ```js import { Experiment } from '@amplitude/experiment-js-client'; const experiment = Experiment.initialize( 'DEPLOYMENT_KEY', { exposureTrackingProvider: { track: (exposure) => { // TODO: Implement exposure tracking // analytics.track('$exposure', exposure) } } } ); ``` {% /tab %} {% /tabs %} ### 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](#custom-logging) for details. | `LogLevel.Error` | | `loggerProvider` | Custom logger implementation. Must implement the `Logger` interface. Go to [Custom logging](#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()`](#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](#fetch) remote evaluation variants on [start](#start). If false, never fetch on start. | `true` | | `pollOnStart` | Poll for local evaluation flag configuration updates every minute on [start](#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 | {% callout type="info" heading="EU data center" %} If you're using Amplitude's EU data center, configure the `serverZone` option on initialization to `eu`. {% /callout %} ### 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](#providers) interfaces to enable a more streamlined developer experience by making it easier to **manage user identity** and **track exposures events**. {% accordion title="Amplitude integration" %} The Amplitude Experiment SDK is set up to integrate with the Amplitude Analytics SDK. ```js import * as amplitude from '@amplitude/analytics-browser'; import { Experiment } from '@amplitude/experiment-js-client'; amplitude.init('API_KEY'); const experiment = Experiment.initializeWithAmplitudeAnalytics('DEPLOYMENT_KEY'); ``` When you use the integration initializer, it configures implementations of the [user provider](#user-provider) and [exposure tracking provider](#exposure-tracking-provider) interfaces to pull user data from the Amplitude Analytics SDK and track exposure events. {% /accordion %} {% accordion title="Segment integration" %} When you use Segment as your analytics provider, configure the integration with Experiment manually on initialization with an instance of the exposure tracking provider. Ensure this happens after the analytics SDK loads and initializes. ```js analytics.ready(() => { const experiment = Experiment.initialize('DEPLOYMENT_KEY', { exposureTrackingProvider: { track: (exposure) => { analytics.track('$exposure', exposure) } } }); }); ``` When [fetching variants](#fetch), pass the segment anonymous ID and user ID for the device ID and user ID, respectively. ```js await experiment.fetch({ user_id: analytics.user().id(), device_id: analytics.user().analyticsId(), }); ``` {% /accordion %} ## Fetch Fetches variants for a [user](/docs/feature-experiment/data-model#users) and stores the results in the client for fast access. The function [remote evaluates](/docs/feature-experiment/remote-evaluation) the user for flags associated with the deployment used to initialize the SDK client. ```js fetch(user?: ExperimentUser): Promise ``` | Parameter | Requirement | Description | | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user` | optional | Explicit [user](/docs/feature-experiment/data-model#users) information to pass with the request to evaluate. The SDK merges this user information with user information provided from [integrations](#integrations) through the [user provider](#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". ```js const user = { user_id: 'user@company.com', device_id: 'abcdefg', user_properties: { 'premium': true, }, }; await experiment.fetch(user); ``` If you're using an [integration](#integrations) or a custom [user provider](#user-provider) then you can fetch without inputting the user. ```js await experiment.fetch(); ``` {% callout type="tip" heading="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](/docs/feature-experiment/remote-evaluation). Remote user-property sync through a separate system has no timing guarantees for `fetch()`, which can create a race condition. {% /callout %} 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](#configuration) during SDK client initialization. {% accordion title="Account-level bucketing and analysis (v1.1.0+)" %} If your organization has purchased the [Accounts add-on](/docs/analytics/account-level-reporting) you may perform bucketing and analysis on groups rather than users. Reach out to your representative to gain access to this beta feature. Include groups in the user sent with the fetch request (recommended), or identify groups with the user through a group identify call from the [Group Identify API](/docs/apis/analytics/group-identify) or through [`setGroup()` from an analytics SDK](/docs/sdks/analytics/browser/browser-sdk-2#user-groups). ```js await fetch({ user_id: 'user@company.com', device_id: 'abcdefg', user_properties: { 'premium': true, }, groups: {'org name': ['Amplitude']} }); ``` To pass freeform group properties, refer to this example: ```js await fetch({ user_id: 'user@company.com', device_id: 'abcdefg', user_properties: { 'premium': true, }, group_properties: {'org name': ['Amplitude']} }); ``` {% /accordion %} ## Start {% callout type="info" heading="Fetch vs start" %} Use `start` if you're using client-side [local evaluation](/docs/feature-experiment/local-evaluation). If you're only using [remote evaluation](/docs/feature-experiment/remote-evaluation), call [fetch](#fetch) instead of `start`. {% /callout %} 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. ```js start(user?: ExperimentUser): Promise ``` | Parameter | Requirement | Description | | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `user` | optional | Explicit [user](/docs/feature-experiment/data-model#users) information to pass with the request to fetch variants. This user information merges with user information from any [integrations](#integrations) through the [user provider](#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](#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. {% code-group %} ```js Amplitude await experiment.start(); ``` ```js Third party const user = { user_id: 'user@company.com', device_id: 'abcdefg', user_properties: { premium: true } }; await experiment.start(user); ``` {% /code-group %} 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](/docs/feature-experiment/data-model#variants) for a [flag or experiment](/docs/feature-experiment/data-model#flags-and-experiments) from the SDK client's local store. {% callout type="info" heading="Automatic exposure tracking" %} When you use an [integration](#integrations) or set a custom [exposure tracking provider](#exposure-tracking-provider), `variant()` automatically tracks an exposure event through the tracking provider. To disable this functionality, [configure](#configuration) `automaticExposureTracking` to be `false`, and track exposures manually using [`exposure()`](#exposure). {% /callout %} ```js variant(key: string, fallback?: string | Variant): Variant ``` | Parameter | Requirement | Description | | ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | required | The **flag key** to identify the [flag or experiment](/docs/feature-experiment/data-model#flags-and-experiments) 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. ```js const variant = experiment.variant(''); if (variant.value === 'on') { // Flag is on } else { // Flag is off } ``` {% callout type="info" heading="Access a variant's payload" %} A variant may also be configured with a dynamic [payload](/docs/feature-experiment/data-model#variants) of arbitrary data. Access the `payload` field from the variant object after checking the variant's `value`. ```js const variant = experiment.variant(''); if (variant.value === 'on') { const payload = variant.payload; } ``` {% /callout %} 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. ```js const variant = experiment.variant('', { value: 'control' }); if (variant.value === 'control') { // Control } else if (variant.value === 'treatment') { // Treatment } ``` ## All Access all [variants](/docs/feature-experiment/data-model#variants) stored by the SDK client. ```js all(): Variants ``` ## Clear Clear all [variants](/docs/feature-experiment/data-model#variants) in the cache and storage. ```js clear(): void ``` You can call `clear` after user logout to clear the variants in cache and storage. ```js experiment.clear(); ``` ## Exposure Manually track an [exposure event](/docs/feature-experiment/under-the-hood/event-tracking#exposure-events) for the current variant of the given flag key through configured [integration](#integrations) or custom [exposure tracking provider](#exposure-tracking-provider). Generally used in conjunction with setting the `automaticExposureTracking` [configuration](#configuration) optional to `false`. ```js exposure(key: string): void ``` | Parameter | Requirement | Description | | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | required | The **flag key** to identify the [flag or experiment](/docs/feature-experiment/data-model#flags-and-experiments) variant to track an [exposure event](/docs/feature-experiment/under-the-hood/event-tracking#exposure-events) for. | ```js const variant = experiment.variant(''); // Do other things... experiment.exposure(''); if (variant === 'control') { // Control } else if (variant === 'treatment') { // Treatment } ``` ## Providers {% callout type="tip" heading="Integrations" %} If you use Amplitude or Segment analytics SDKs along side the Experiment Client SDK, Amplitude recommends you use an [integration](#integrations) instead of implementing custom providers. {% /callout %} 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()`](#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). ```js interface ExperimentUserProvider { getUser(): ExperimentUser; } ``` To use your custom user provider, set the `userProvider` [configuration](#configuration) option with an instance of your custom implementation on SDK initialization. ```js const experiment = Experiment.initialize('', { userProvider: new CustomUserProvider(), }); ``` ### Exposure tracking provider Amplitude highly recommends implementing an exposure tracking provider. [Exposure tracking](/docs/feature-experiment/under-the-hood/event-tracking#exposure-events) increases the accuracy and reliability of experiment results and improves visibility into which flags and experiments a user is exposed to. ```js title="ExposureTrackingProvider" 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](#initialize) the SDK client lives within, and for the same user that variants were [fetched](#fetch) for. To use your custom user provider, set the `exposureTrackingProvider` [configuration](#configuration) option with an instance of your custom implementation on SDK initialization. ```js const experiment = Experiment.initialize('', { 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](/docs/feature-experiment/local-evaluation), [server-side rendering](/docs/feature-experiment/advanced-techniques/server-side-rendering), or integration testing on specific variants. To bootstrap the client, set the flags and variants in the `initialVariants` [configuration](#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. ```js const experiment = Experiment.initialize('', { 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. ```js title="HttpClient" export interface SimpleResponse { status: number; body: string; } export interface HttpClient { request( requestUrl: string, method: string, headers: Record, data: string, timeoutMillis?: number, ): Promise; } ``` To use your custom HTTP client, set the `httpClient` [configuration](#configuration) option with an instance of your implementation on SDK initialization. ```js const experiment = Experiment.initialize('', { 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. ```js import { Experiment, LogLevel } from '@amplitude/experiment-react-native-client'; // Only log errors const experiment = Experiment.initialize('', { logLevel: LogLevel.Error }); // Log errors and warnings const experiment = Experiment.initialize('', { logLevel: LogLevel.Warn }); // Log everything (verbose) const experiment = Experiment.initialize('', { logLevel: LogLevel.Verbose }); ``` ### Custom logger Implement the `Logger` interface to use your own logging solution. ```js 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('', { loggerProvider: new CustomLogger(), logLevel: LogLevel.Warn }); ``` ### Debug flag (deprecated) The `debug` configuration flag is deprecated. Use `logLevel` instead. ```js // Deprecated: Sets logLevel to Debug const experiment = Experiment.initialize('', { debug: true }); // Preferred: Use logLevel instead const experiment = Experiment.initialize('', { logLevel: LogLevel.Debug }); ```