--- title: Initialize the React Native SDK slug: feature-experimentation/docs/initialize-sdk-reactnative-prior-to-v4 docTags: createdAt: 2026-08-05T20:40:01.000Z --- Use the `createInstance` method to initialize the React Native SDK and instantiate an instance of the `ReactSDKClient `class. Each client corresponds to the datafile representing the state of a project for a certain environment. ## Version SDK v3.0.0 and higher ## Description The `createInstance` method accepts a configuration object to configure Optimizely. Some parameters are optional because the React SDK provides a default implementation, but you may want to override these for your production environments. For example, you may want to override these to configure an [error handler](docId\:HpTq-_qYjwf2Vzg5DRnhm) and [logger](docId\:JIhfxkhnm4ACNaEfVWsmO) to catch issues, an event dispatcher to manage network calls, and a User Profile Service to ensure sticky bucketing. ## Parameters The following table lists the required and optional parameters in React (created by passing in a Config object. The Config class consists of these fields). | Parameter | Type | Description | | ------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | \`datafile\` \_optional\_ | string | The JSON string representing the project. At least one of sdkKey or datafile must be provided. | | \`sdkKey\` \_optional\_ | string | The key associated with an environment in the project. At least one of sdkKey or datafile must be provided. | | \`eventDispatcher\` \_optional\_ | object | An event handler to manage network calls. | | \`logger\` \_optional\_ | object | A logger implementation to log issues. | | \`errorHandler\` \_optional\_ | object | An error handler object to handle errors. | | \`userProfileService\` \_optional\_ | object | A user profile service. | | \`datafileOptions\` \_optional\_ | object | Object with configuration for automatic datafile management. Can have \`autoUpdate\` (boolean), \`urlTemplate\` (string), and \`updateInterval\` (number) properties. | | \`defaultDecideOptions\` \_optional\_ | Array | Array of \`OptimizelyDecideOption\` enums. When the Optimizely client is constructed with this parameter, it sets default decide options which are applied to all the Decide calls made during the lifetime of the Optimizely client. Additionally, you can pass options to individual Decide methods (does not override defaults). For details on decide options, see \[OptimizelyDecideOption]\(https\://docs.developers.optimizely.com/feature-experimentation/docs/usedecision-reactnative-prior-to-v4#-optimizelydecideoption). | ## Returns Instantiates an instance of the `ReactSDKClient` class, a variation of the underlying JavaScript SDK Optimizely Client. ## Example In the React SDK, you can provide either `sdkKey` or `datafile` or both. - When initializing with just the SDK key, the datafile is automatically downloaded - When initializing with just the datafile, the SDK uses the given datafile. - When initializing with both the SDK key and datafile, the SDK uses the given datafile to start, then download the latest version of the datafile in the background. ### Instantiate using datafile You can instantiate with a hard-coded datafile. If you do not pass in an SDK key, the React Native SDK Client does not automatically sync newer versions of the datafile. Any time you retrieve an updated datafile, just re-instantiate the same client. The hard-coded datafile can be a JSON or a valid JSON string. To get the hard-coded datafile, copy the datafile JSON string from [the app](docId:8_kRh18IHN_0bW1xf7jYv). Typically you would want to copy the datafile string at the latest point possible pre-release. ```javascript import { createInstance } from '@optimizely/react-sdk'; const optimizely = createInstance({ datafile: optimizelyDatafile, }) ``` ### Instantiate using SDK key To instantiate using SDK Key, obtain the SDK Key from your project's settings page, then pass `sdkKey` as a string property in the options object you pass to the `createInstance` method. ```javascript import { createInstance } from '@optimizely/react-sdk'; const optimizely = createInstance({ sdkKey: '', }); ``` When you provide the `sdkKey`, the SDK instance downloads the datafile associated with that `sdkKey`. When the download completes, the SDK instance updates itself to use the downloaded datafile. ### Instantiate offline with SDK key The React Native SDK provides default datafile caching to support fast initialization and offline mode. This means you can initialize using the SDK key even when there is no Internet connectivity. Once downloaded, the datafile is stored in the cache on the user's device. When the SDK is initialized the next time, it uses the datafile from the cache if available and resolves the ready promise. It then continues to load the latest datafile from the server. This results in faster SDK initialization. ### Render an `OptimizelyProvider` with a client and user To use React Native SDK components inside your app, render an `OptimizelyProvider` as the parent of your root app component. Provide your Optimizely instance as the `optimizely` prop, and a `user` object: ```javascript import { OptimizelyProvider, createInstance } from '@optimizely/react-sdk'; const optimizely = createInstance({ datafile: window.datafile, }); // using a function component export default function App() { return ( '}}> ); } // or a class component class App extends React.Component { render() { return ( '}}> ); } } ``` ## Notes ### Customize datafile management behavior To customize datafile management behavior, provide a `datafileOptions` object property inside the `options` object passed to `createInstance`. The table lists the supported customizable options. | Option | Type | Explanation | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `autoUpdate` | boolean | When true, and `sdkKey` was provided in `createInstance` options, automatic updates are enabled on this instance. The default value is `false`. | | `updateInterval` | number | When automatic updates are enabled, this controls the update interval. The unit is milliseconds. The minimum allowed value is 1000 (1 second). The default value is 300000 milliseconds (5 minutes). | | `urlTemplate` | string | A format string used to build the URL from which the SDK will request datafiles. Instances of `%s` is replaced with the `sdkKey`. When not provided, the SDK will request datafiles from the Optimizely CDN. | The following example shows how to customize datafile management behavior: ```javascript import { createInstance } from '@optimizely/react-sdk'; const optimizely = createInstance({ sdkKey: 'YOUR_SDK_KEY', datafileOptions: { autoUpdate: true, updateInterval: 600_000, // 10 minutes in milliseconds urlTemplate: 'http://localhost:5000/datafiles/%s.json', }, }); ``` ## Dispose of the client For effective resource management with the Optimizely React Native SDK, you must properly close the Optimizely client instance when it is no longer needed. This is done by calling `optimizely.close()`. The `.close()` method ensures that the processes and queues associated with the instance are properly released. This is essential for preventing memory leaks and ensuring that the application runs efficiently, especially in environments where resources are limited or in applications that create and dispose of many instances over their lifecycle. See [Close Optimizely on application exit](docId\:IIEDjL-zDtvMdFQG7Yeb8). ## `ODPManager` `OdpManager` contains all the logic supporting Real-Time Audiences for Feature Experimentation-related features, including audience segments. You must configure this parameter to use Real-Time Audiences for Feature Experimentation. The React SDK enables the Real-Time Audiences for Feature Experimentation methods by default. But, the methods do nothing unless you have enabled and configured Real-Time Audiences for Feature Experimentation. :::hint{type="info"} **Note** If necessary, to disable Real-Time Audiences for Feature Experimentation altogether, set `disabled: true` in the `odpOptions`. See the following code sample for information. ::: The following settings are optionally configurable when the React Native SDK is initialized: - **ODP SegmentsCache size** – `segmentsCacheSize` - **Default** – 100 - Set to 0 to disable caching. - **ODP SegmentsCache timeout** (in seconds) – `segmentsCacheTimeout` - **Default** – 600 secs (10 minutes) - Set to 0 to disable timeout (never expires). - **ODP enable** – `disabled` - **Default** – false (enabled) - When disabled, the React Native SDK disables ODP-related features. The React Native SDK still creates and manages VUID regardless of this flag and supports VUID-based decisions. See [anonymous users](docId\:iKfXFMXe_eqGd2PbD3j6T). - The React Native SDK returns or logs an `odpNotEnabled` error when ODP is disabled and its features are requested. **OdpSegmentManager** This module provides an interface to the remote ODP server for audience segment mappings. It fetches all qualified audience segments for the given user context and returns them as a string array in the completion handler. It also manages an audience segments cache shared for all user contexts. The cache is in memory (not persistent), and rebooting the device or terminating the app resets it. **OdpEventManager** This module provides an interface to the remote ODP server for events. It queues all pending events (persistent) and sends them (in batches of up to 10) to the ODP server when all resources are available, including network connection and ODP public key (in the SDK's datafile). The React Native SDK does not have direct access to OdpManager, OdpSegmentManager, nor OdpEventManager. These are managed by the underlying Javascript SDK. There are configuration options that can be set during the Optimizely client instantiation. :::hint{type="info"} - **Note** The React Native SDK tries to dispatch all events (stored in a persistent queue and retried on recoverable errors) but does not guarantee completion. - The React Native SDK does not have direct access to `OdpManager`, `OdpSegmentManager`, nor `OdpEventManager`. These are managed by the underlying Javascript SDK. There are configuration options that can be set during the Optimizely client instantiation. ::: ```javascript // You must first configure Real-Time Audiences for Feature Experimentation import { createInstance } from '@optimizely/react-sdk'; const optimizely = createInstance({ sdkKey: 'YOUR_SDK_KEY', //...other Config options // The most common Real-Time Audiences for Feature Experimentation control is to explicitly disable the feature odpOptions: { disabled: true, }, // Other options are as defined by OdpOptions in the Javascript SDK // https://github.com/optimizely/javascript-sdk/blob/master/lib/shared_types.ts }); ``` ## Source files The language and platform source files containing the implementation for React Native SDK are available on [GitHub](https://github.com/optimizely/react-sdk/blob/master/src/index.ts).