Disclaimer: This website requires JavaScript to function properly. Some features may not work as expected. Please enable JavaScript in your browser settings for the best experience.

Optimizely will be sunsetting Full Stack Experimentation on July 29, 2024. See the recommended Feature Experimentation migration timeline and documentation.

Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideLegal TermsGitHubDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide

Initialize SDK

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

Use the createInstance method to initialize the React 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 v1.0.0

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

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.

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

First, get a copy of the datafile from our server by including the following script in the of your web application. This script adds the datafile on the window variable window.optimizelyDatafile.

<script src="https://cdn.optimizely.com/datafiles/<Your_SDK_Key>.json/tag.js"></script>

Once you have a datafile, you can instantiate an Optimizely client.

import * as optimizelyReactSDK from '@optimizely/react-sdk';

// Instantiate an Optimizely client
const optimizely = optimizelyReactSDK.createInstance({
  datafile: window.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 * as optimizelyReactSDK from '@optimizely/react-sdk';

// Instantiate an Optimizely client
const optimizely = optimizelyReactSDK.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. This initialize method relies on continuous Internet connectivity (in contrast, in the React Native SDK, you can initialize with an SDK key even while your app is offline.)

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:

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

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

class AppWrapper 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.

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: 600000, // 10 minutes in milliseconds
    urlTemplate: 'http://localhost:5000/datafiles/%s.json',
  },
});

Considerations when using development mode

If you have created your React application using Create React App or are using a different type of development environment that uses hot reloading, there is a possibility to experience unusual behavior.

When running your application in development mode with hot reloading, for example, when using npm start, you may see that the Optimizely SDK is initialized more than once. This may cause inconsistent behavior, such as the page re-rendering multiple times or users being bucketed into incorrect variations.

This is not a problem with the Optimizely React SDK, instead, this happens when you wrap your application in React.StrictMode, which purposely renders the application twice in development mode to detect potential problems. To avoid this, please disable the strict mode for the top-level component and move it to the lower-level components.

When building your app for production using npm run build and hosting it on a web server, the Optimizely React SDK is not initialized more than once.

Source files

The language/platform source files containing the implementation for React SDK are at index.ts.