{% callout type="warning" heading="" %} The legacy SDK receives only bug fixes until deprecation. We recommend upgrading to `v1.0.0+`, which supports SDK integrations, React Native Web, Expo, and more. {% /callout %} Official documentation for Amplitude Experiment's Client-side React Native SDK. ## Install {% callout type="warning" heading="Web compatibility" %} Experiment React Native SDK is only compatible with iOS and Android React Native projects. Use the [JavaScript SDK](/docs/sdks/experiment-sdks/experiment-javascript) to support all three platforms. {% /callout %} Install the Experiment JavaScript Client SDK. {% code-group %} ```bash npm npm install --save @amplitude/experiment-react-native-client ``` ```bash yarn yarn add @amplitude/experiment-react-native-client ``` {% /code-group %} {% callout type="tip" heading="Quick start" %} 1. [Initialize the experiment client](#initialize) 2. [Fetch variants for the user](#fetch) 3. [Access a flag's variant](#variant) ```js // (1) Initialize the experiment client await Experiment.initialize(''); // (2) Fetch variants for a user const user = { user_id: 'user@company.com', device_id: 'abcdefg', user_properties: { 'premium': true, }, }; await Experiment.fetch(user); // (3) Lookup a flag's variant const variant = await Experiment.variant(''); if (variant.value === 'on') { // Flag is on } else { // Flag is off } ``` {% /callout %} ## Core functions The following functions make up the core of the Experiment client-side SDK. {% callout type="info" heading="Async functions" %} Native SDKs run internally, so you need to `await` the result of all functions. {% /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. ```js initialize(apiKey: string, config?: ExperimentConfig): Promise ``` | 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). ```js const experiment = await Experiment.initialize(''); ``` #### 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](#providers) interfaces to enable a more streamlined developer experience by making it easier to **manage user identity** and **track exposures events**. {% callout type="info" heading="Amplitude integration" %} The Amplitude Experiment SDK is set up to integrate with the Amplitude Analytics SDK. Update your SDK versions to the latest, and use the special integration initialization function. ```js hl_lines="2" await Amplitude.getInstance().init(''); await Experiment.initializeWithAmplitudeAnalytics(''); ``` If you are using a custom instance name for analytics, set the same value in the `instanceName` [configuration option](#configuration) in the experiment SDK. The integration initializer 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. **Supported Versions** | Analytics SDK Version | Experiment SDK Version | | --------------------- | ---------------------- | | `2.8.0+` | `0.6.0+` | {% /callout %} #### Configuration Configure the SDK client during initialization. | Name | Description | Default Value | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | | `debug` | Enable additional debug logging within the SDK. Should be set to false in production builds. | `false` | | `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). | `{}` | | `serverUrl` | The host to fetch variants from. | `https://api.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` | | `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` | {% callout type="info" heading="EU data center" %} If you're using Amplitude's EU data center, configure the `serverUrl` option on initialization to `https://api.lab.eu.amplitude.com` {% /callout %} ### 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 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". ```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, 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 %} {% callout type="tip" heading="Timeout and retries" %} 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. {% /callout %} ### 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): Promise ``` ```js variantWithFallback(key: string, fallback: Variant): Promise ``` | 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 = await Experiment.variant(''); if (variant.value === 'on') { // Flag is on } else { // Flag is off } ``` {% callout type="info" heading="Access the 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 = await 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 = await Experiment.variantWithFallback('', { value: 'control' }); if (variant === 'control') { // Control } else if (variant === 'treatment') { // Treatment } ``` ### All Access all [variants](/docs/feature-experiment/data-model#variants) stored by the SDK client. ```js all(): Promise ``` ### 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): Promise ``` | 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 = await Experiment.variant(''); // Do other things... await Experiment.exposure(''); if (variant === 'control') { // Control } else if (variant === 'treatment') { // Treatment } ```