Initialize the JavaScript (Browser) SDK

Use the createInstance method to initialize the JavaScript (Browser) SDK and instantiate an instance of the Optimizely client class that exposes API methods like Decide methods. Each client corresponds to the datafile representing the state of a project for a certain environment.

Version

SDK v3.2.1 and higher

Description

The createInstance method accepts a configuration object to configure Optimizely Feature Experimentation.

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 properties of the config object:

Parameter	Type	Description
datafile optional	string	The JSON string representing the project. At least one of sdkKey or datafile must be provided.
sdkKey optional	string	The key associated with an environment in the project. At least one of sdkKey or datafile must be provided.
eventDispatcher optional	object	An event dispatcher to manage network calls. An object with a dispatchEvent method.
logger optional	object	A logger implementation to log messages. An object with a log method.
errorHandler optional	object	An error handler object to handle errors. An object with a handleError method
userProfileService optional	object	A user profile service. An object with lookup and save methods.
jsonSchemaValidator optional	object	To perform JSON schema validation on datafiles, import the validator from `'@optimizely/optimizely-sdk/dist/optimizely.json_shema_validator.min.js'`, and pass it as this initialization option. Skipping JSON schema validation enhances performance during initialization.
datafileOptions optional	object	Object with configuration for automatic datafile management. Can have `autoUpdate` (Boolean), `urlTemplate` (string), and `updateInterval` (number) properties.
access_token optional	string	Server-side (only) Optimizely Feature Experimentation SDKs can use an access token (with sdk key) to fetch the datafile from an authenticated endpoint. Find your datafile access token in the Optimizely app at Settings>Environments. Select your secure environment, and copy the Datafile access token.
defaultDecideOptions optional	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 example code, see OptimizelyDecideOption.

Returns

Instantiates an instance of the Optimizely class.

Examples

In the JavaScript SDK, you can provide either a 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. Then, instantiate the client.

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

// Replace <YOUR_SDK_KEY> to get the datafile
const sdkKey = '<YOUR_SDK_KEY>';
const DATAFILE_URL = `https://cdn.optimizely.com/datafiles/${sdkKey}.json`;
const response = await fetch(DATAFILE_URL);
const datafile = await response.json();
const optimizely = createInstance({
  datafile
});

if (!optimizely) {
  // there was an error creating the instance, handle error
} else {
  // Use optimizelyClient to run experiments
}

<!--Step 1: add a <script> tag in your <head> tag: 
 <!-- Replace <YOUR_SDK_KEY> to get the datafile -->
<script src="https://cdn.optimizely.com/datafiles/<YOUR_SDK_KEY>.json/tag.js"></script>

<!--Step 2. after the <body> tag, add a new <script> tag to instantiate an Optimizely client  from the datafile:-->
<script>
    var optimizely = window.optimizelySdk.createInstance({
        datafile: window.optimizelyDatafile,
    });
</script>

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.

For simple applications, all you need to provide to instantiate a client is a datafile specifying the project configuration for a given environment. For most advanced implementations, you will want to customize the logger or error handler for your specific requirements.

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/optimizely-sdk';
const optimizely = createInstance({
  sdkKey: '<YOUR_SDK_KEY>', // Provide the sdkKey of your desired environment here

When you provide the sdkKey, the SDK instance asynchronously downloads the datafile associated with that sdkKey. When the download completes, the SDK instance updates itself to use the downloaded datafile. You can use the onReady promise method to wait for the datafile to be downloaded before using the instance.

import { createInstance } from '@optimizely/optimizely-sdk';
const optimizely = createInstance({
  sdkKey: '<YOUR_SDK_KEY>', // Provide the sdkKey of your desired environment here
});
if (!optimizely) {
  // there was an error creating the instance, handle error
} else {
  // Use optimizelyClient
  optimizely.onReady().then(({ success, reason }) => {
    if (success) {
      // optimizelyClientInstance is ready to use, with datafile downloaded from the
      // Optimizely CDN
    } else {
      // this optimizelyClientInstance cannot be used
      console.log(`client initialization unsuccessful, reason: ${reason}`);
    }
  });
}

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.

Option	Type	Description
autoUpdate	boolean	When true, and `sdkKey` was provided in `createInstance` options, automatic updates are enabled on this instance. The default value is `false`.
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 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/optimizely-sdk';

const optimizely = createInstance({
  sdkKey: '<YOUR_SDK_KEY>',
  datafileOptions: {
    autoUpdate: true,
    updateInterval: 600000, // 10 minutes in milliseconds
    urlTemplate: 'http://localhost:5000/datafiles/%s.json',
  },
});

onReady details

Use the onReady method to wait until the download is complete and the SDK is ready to use.

The onReady method returns a Promise representing the initialization process.
onReady accepts an optional timeout argument (defined in milliseconds) that controls the maximum duration that the returned Promise will remain in the pending state. If timeout is not provided, it defaults to 30 seconds.

import { createInstance } from '@optimizely/optimizely-sdk';
let optimizely = createInstance({
  sdkKey: '<YOUR_SDK_KEY>',
});
if (!optimizely) {
  // there was an error creating the instance, handle error
} else {
  // Use optimizelyClient
  optimizely.onReady().then(result => {
    // Returned Promise is fulfilled with a result object
    console.log(result.success); // true if the instance fetched a datafile and is now ready to use
    console.log(result.reason); // If success is false, reason contains an error message
  });
  // Provide a timeout in milliseconds - promise will resolve if the datafile still is not available after the timeout
  optimizely.onReady({ timeout: 5000 }).then(result => {
    // Returned Promise is fulfilled with a result object
    console.log(result.success); // true if the instance fetched a datafile and is now ready to use
    console.log(result.reason); // If success is false, reason contains an error message
  });
};

The Promise returned from the onReady method is fulfilled with a result object containing a boolean success property.

When the success property is true, the instance is ready to use with a valid datafile. When the success property is false, there is also a reason string property describing the failure. Failure can be caused by expiration of the timeout, network error, unsuccessful HTTP response, datafile validation error, or the instance's close method being called.

Set a fallback datafile

If you provide an sdkKey and a static fallback datafile for initialization, the SDK uses the fallback datafile immediately if it is valid while simultaneously downloading the datafile associated with the sdkKey. After the download completes, if the downloaded datafile is valid and has a more recent revision than the fallback datafile, the SDK updates the instance to use the downloaded datafile.

import { createInstance } from '@optimizely/optimizely-sdk';
const datafile = '{"version": "4", "rollouts": [], "typedAudiences": [], "anonymizeIP": false, "projectId": "12345", "variables": [], "featureFlags": [], "experiments": [], "audiences": [], "groups": [], "attributes": [], "botFiltering": false, "accountId": "12345", "events": [], "revision": "1"}'; 
const optimizely = createInstance({
  sdkKey: '<Your_SDK_Key>',
  datafile,
});
// optimizelyClient can be used immediately with the given datafile, but
// will download the latest datafile and update itself

Source files

The source code files containing the implementation for the JavaScript (Browser) SDK are available on GitHub.