Initialize the React SDK
Initialize the Optimizely Feature Experimentation React SDK in your application.
Use thecreateInstance method to initialize the React SDK and instantiate an instance of theReactSDKClient 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
ThecreateInstance 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 anerror handler andlogger to catch issues, anevent dispatcher to manage network calls and aUser Profile Service to ensuresticky bucketing.
Parameters
The 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 |
|---|---|---|
| string | The JSON string representing the project. Either an SDK key or datafile (or both) must be provided. |
| string | The key associated with an environment in the project. At least one of sdkKey or datafile must be provided. |
| object | An event handler to manage network calls. |
| object | A logger implementation to log issues. |
| object | An error handler object to handle errors. |
| object | A user profile service. |
| object | Object with configuration for automatic datafile management. Can have |
| Array | Array of |
Returns
Instantiates an instance of the Optimizely Feature Experimentation class.
Example
In the React SDK, you can provide eithersdkKey ordatafile or both.
- When initializing withjust the datafile, the SDK uses the given datafile.
- When initializing withjust the SDK key, the datafile is automatically downloaded.
- 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
First, get a copy of the datafile from our server by including the following script in the<head> of your web application. This script adds the datafile on the global window variablewindow.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 { createInstance } from '@optimizely/react-sdk';const optimizely = createInstance({ datafile: window.optimizelyDatafile,})Instantiate using SDK key
To instantiate using the SDK key, obtain the SDK key from your project's settings page, then passsdkKey as a string property in the options object you pass to thecreateInstance method.
import { createInstance } from '@optimizely/react-sdk';const optimizely = createInstance({ sdkKey: 'YOUR_SDK_KEY',});When you provide thesdkKey, the SDK instance downloads the datafile associated with thatsdkKey. 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 theReact Native SDK, you can initialize with an SDK Key even while your app is offline.)
Render anOptimizelyProvider with a client and user
OptimizelyProvider with a client and userTo use React SDK components inside your app, render anOptimizelyProvider as the parent of your root app component. Provide your Optimizely instance as theoptimizely prop and auser object:
import { OptimizelyProvider, createInstance } from '@optimizely/react-sdk';const optimizely = createInstance({ datafile: window.datafile,});// using a function componentexport default function App() { return ( <OptimizelyProvider optimizely={optimizely} user={{id: '<Your_User_Id>'}}> <App /> </OptimizelyProvider> );}// or a class componentclass 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 adatafileOptions object property inside theoptions object passed tocreateInstance. The table lists the supported customizable options.
| Option | Type | Explanation |
|---|---|---|
| autoUpdate | boolean | When true, andsdkKey was provided increateInstance options, automatic updates are enabled on this instance. The default value isfalse. |
| 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 will be replaced with thesdkKey. 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', },});Considerations when using development mode
If you have created your React application usingCreate React App or are using a different type of development environment that uses hot reloading, there is a possibility of experiencing unusual behavior.
When running your application in development mode with hot reloading, for example, when usingnpm start, you may see that the Optimizely Feature Experimentation 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 Feature Experimentation React SDK. Instead, this happens when you wrap your application inReact.StrictMode, which purposely renders the application twice in development mode to detect potential issues. To avoid this, disable the strict mode for the top-level component and move it to the lower-level components.
When building your app for production usenpm run build and hosting it on a web server, the Optimizely Feature Experimentation React SDK is not initialized more than once.
Dispose of the client
For effective resource management with the Optimizely React SDK, you must properly close the Optimizely client instance when it is no longer needed. This is done by callingoptimizely.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.
SeeClose Optimizely Feature Experimentation React SDK on application exit.
OdpManager
OdpManager contains all the logic supporting Real-Time Audiences for Feature Experimentation-related features, including audience segments.
The React SDK enables the Real-Time Audiences for Feature Experimentation methods by default. But, the methods do nothing unless you have enabled and configuredReal-Time Audiences for Feature Experimentation.
If necessary, to disable Real-Time Audiences for Feature Experimentation altogether, setdisabled: true in theodpOptions. See the following sample code for information.
The following settings are optionally configurable when the React 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 SDK will disable ODP-related features. The React SDK still creates and manages VUID regardless of this flag and supports VUID-based decisions. Seeanonymous users.
- The React SDK returns or logs an
odpNotEnablederror 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 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).
📘
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, norOdpEventManager. These are managed by the underlying Javascript SDK. There are configuration options that can be set during the Optimizely client instantiation.
// You must configure Real-Time Audiences for Feature Experimentationimport { 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 SDK are available onGitHub.
Updated 17 days ago