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).
Parameter | Type | Description |
---|---|---|
datafile | string | The JSON string representing the project. At least one of sdkKey or datafile must be provided. |
sdkKey | string | The key associated with an environment in the project. At least one of sdkKey or datafile must be provided. |
eventDispatcher | object | An event handler to manage network calls. |
logger | object | A logger implementation to log issues. |
errorHandler | object | An error handler object to handle errors. |
userProfileService | object | A user profile service. |
datafileOptions | object | Object with configuration for automatic datafile management. Can have |
defaultDecideOptions | 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 overrides defaults). For details on decide options, see OptimizelyDecideOption. |
Returns
Instantiates an instance of the Optimizely 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
OptimizelyProvider
with a client and userTo 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.
autoUpdate | boolean | When true, and |
---|---|---|
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 |
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',
},
});
Source files
The language/platform source files containing the implementation for React SDK are at index.ts.
Updated 4 months ago