Dev guideAPI Reference
Dev guideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Initialize the React Native SDK

This topic describes how to initialize the Optimizely React Native SDK in your application.

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 Feature Experimentation.

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

ParameterTypeDescription
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.
defaultDecideOptions
optional
ArrayArray 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 overrides defaults). For details on decide options, see 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 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 React SDK Client will 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. Typically you would want to copy the datafile string at the latest point possible pre-release.

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.

import { createInstance } from '@optimizely/react-sdk';

const optimizely = createInstance({
  sdkKey: '<Your_SDK_Key>',
});

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 Feature Experimentation instance as the optimizely prop, and a user object:

import { OptimizelyProvider, createInstance  } from '@optimizely/react-sdk';

const optimizely = createInstance({
  datafile: window.datafile,
});

// using a function component
export default function App() {
 return (
   <OptimizelyProvider
     optimizely={optimizely}
     user={{id: '<Your_User_Id>'}}>
     <App />
   </OptimizelyProvider>
 );
}

// or a class component
class App extends React.Component {
  render() {
    return (
      <OptimizelyProvider
      	optimizely={optimizely}
  			user={{id: '<Your_User_Id>'}}>
        <App />
      </OptimizelyProvider>
    );
  }
}

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.

OptionTypeExplanation
autoUpdatebooleanWhen true, and sdkKey was provided in createInstance options, automatic updates are enabled on this instance. The default value is false.
updateIntervalnumberWhen 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).
urlTemplatestringA 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.

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',
  },
});

ODPManager

OdpManager contains all the logic supporting Advanced Audience Targeting-related features, including audience segments.

The React SDK enables the Advanced Audience Targeting methods by default. But, the methods do nothing unless you have enabled and configured the Advanced Audience Targeting integration.

If necessary, to disable Advanced Audience Targeting altogether, set disabled: true in the odpOptions. See the following sample code for more information.

OdpSegmentManager

This module provides an interface to the remote ODP server for audience segment mappings.

It fetches all qualified segments for the given user context and returns them as a string array in the completion handler.

It also manages a segment's 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 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.

📘

Notes

  • The React SDK tries to dispatch all events (stored in a persistent queue and retried on recoverable errors) but does not guarantee completion.
  • The React 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.
// You must first enable the Advanced Audience Targeting integration

import { createInstance } from '@optimizely/react-sdk';

const optimizely = createInstance({
  sdkKey: '<Your_SDK_Key>',
  //...other Config options
  // The most common Advanced Audience Targeting 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.