HomeGuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog In

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 v2.2.0 and higher

## Description

The `createInstance` method accepts a configuration object to configure Optimizely.

Some parameters are optional because the SDK provides a default implementation, but you may want to override these for your production environments. For example, you may want override these to set up an [error handler](🔗) and [logger](🔗) to catch issues, an event dispatcher to manage network calls, and a User Profile Service to ensure sticky bucketing.

## Parameters

The table below lists the required and optional parameters in React (created by passing in a Config object. The Config class consists of these fields).

**datafile** _optional_ stringThe JSON string representing the project. At least one of sdkKey or datafile must be provided.
**sdkKey** _optional_stringThe key associated with an environment in the project. At least one of sdkKey or datafile must be provided.
**eventDispatcher** _optional_objectAn event handler to manage network calls.
**logger** _optional_ objectA logger implementation to log issues.
**errorHandler** _optional_objectAn error handler object to handle errors.
**userProfileService** _optional_objectA user profile service.
**datafileOptions** _optional_objectObject with configuration for automatic datafile management. Can have `autoUpdate` (boolean), `urlTemplate` (string), and `updateInterval` (number) properties.

## Returns

Instantiates an instance of the Optimzely class.

## Example

In the React SDK, you can provide either `sdkKey` or `datafile` or both.

  • When initializing with just the SDK key, the datafile will be automatically downloaded

  • When initializing with just the datafile, the SDK will use the given datafile.

  • When initializing with both the SDK key and datafile, the SDK will use 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 Optimizely Client will not automatically sync newer versions of the datafile. Any time you retrieve an updated datafile, just re-instantiate the same client. The hardcoded datafile can be a JSON or a valid JSON string. To get the hardcoded datafile, copy the datafile JSON string from [the app](🔗). Typically you would want to copy the datafile string at the latest point possible pre-release.

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

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 out-of-the-box 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 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:

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

**autoUpdate**booleanWhen true, and `sdkKey` was provided in `createInstance` options, automatic updates are enabled on this instance. The default value is `false`.
**updateInterval**numberWhen 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**stringA format string used to build the URL from which the SDK will request datafiles. Instances of `%s` will be 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.

## Source files

The language/platform source files containing the implementation for React SDK are at [index.ts](🔗).