Initialize the JavaScript (Browser) SDK prior to v6

22 min

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

Version

SDK v5.0.0

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 to override these to configure an error handlererror handler and loggerlogger to catch issues, an event dispatcherevent dispatcher to manage network calls, and a User Profile ServiceUser Profile Service to ensure sticky bucketing.

Parameters

The following are the required and optional properties of the configuration object:

Parameter	Type	Description
`datafile` _optional_	string	The JSON string representing the project. Either `sdkKey` or `datafile` is required, but you can provide both. See the [Examples](#examples) section.
`sdkKey` _optional_	string	The key associated with an environment in the project. Either `sdkKey` or `datafile` is required, but you can provide both. See the [Examples](#examples) section.
`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. In SDK versions >= 5.4.0 and \< 6.0.0, can have a `customHeaders` property.
`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 override defaults). See [OptimizelyDecideOption](https://docs.developers.optimizely.com/feature-experimentation/docs/decide-methods-javascript#optimizelydecideoption).
`odpOptions`	`OptimizelySdkSettings`	Contains the logic supporting Real-Time Audiences for Feature Experimentation, including audience segments, sending events, and [VUID management](https://docs.developers.optimizely.com/feature-experimentation/docs/real-time-audiences-for-feature-experimentation#vuids-and-client-side-ids). The JavaScript (Browser) SDK automatically enables the Real-Time Audiences methods. But, the methods do nothing unless you have enabled and configured [Real-Time Audiences for Feature Experimentation](https://docs.developers.optimizely.com/feature-experimentation/docs/real-time-audiences-for-feature-experimentation). To optionally disable Real-Time Audiences, see [OdpManager](https://docs.developers.optimizely.com/feature-experimentation/docs/initialize-sdk-javascript#odpmanager).

Returns

Instantiates an instance of the Optimizely class.

Examples

In the JavaScript SDK, you can provide a sdkKey or datafile or both.

When initializing with just the SDK key – The datafile is automatically downloaded.

When initializing with just the datafile – The SDK uses the given datafile.

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 the Optimizely 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: 
 this adds the datafile on the window variable window.optimizelyDatafile-->

<!-- 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 does not automatically sync newer datafile versions. To retrieve an updated datafile, 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 more advanced implementations, you can customize the loggercustomize the logger or error handlererror handler for your specific requirements.

Instantiate using SDK Key

To instantiate using an SDK key, obtain the SDK Key from your project's settings page and pass it in.

Go to Settings > Environments.

Copy and save the SDK Key for your environment.

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 following table lists the 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 are replaced with the sdkKey. When not provided, the SDK will request datafiles from the Optimizely CDN.
customHeaders	object (Record<string>,<string>)	Lets you pass custom HTTP headers while fetching the datafile. Available in Javascript (Browser) SDK versions >= 5.4.0 and < 6.0.0.

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',
    // Available in Javascript (Browser) SDK versions >= 5.4.0 and < 6.0.0.
    customHeaders: {
      'User-Agent': 'optimizely-sdk/5.4.0 (+https://github.com/optimizely/javascript-sdk)',
    },
});

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 remains 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 the 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

Dispose of the client

For effective resource management with the Optimizely JavaScript (Browser) SDK, you must properly close the Optimizely client instance when it is no longer needed. This is done by calling optimizely.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.

See Close Optimizely on application exitClose Optimizely on application exit.

OdpManager

The OdpManager contains the logic supporting Real-Time Audiences for Feature Experimentation, including audience segments, ODP events, and VUID managementVUID management. You must configure this parameter to use Real-Time Audiences.

The JavaScript (Browser) SDK automatically enables the Real-Time Audiences methods. But, the methods do nothing unless you have enabled and configured Real-Time Audiences for Feature ExperimentationReal-Time Audiences for Feature Experimentation.

Note If necessary, to disable Real-Time Audiences altogether, set disabled: true. See the following sample code.

Initialize the JavaScript (Browser) SDK with Real-Time Audiences disabled.

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

const optimizely = createInstance({
  sdkKey: 'YOUR_SDK_KEY',
  odpOptions: {
    disabled: true,
  },
});

The following settings are optionally configurable when the JavaScript (Browser) 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 JavaScript (Browser) SDK will disable ODP-related features. The JavaScript (Browesr) SDK still creates and manages VUID regardless of this flag and supports VUID-based decisions. See anonymous usersanonymous users.

The JavaScript (Browser) SDK returns or logs an odpNotEnabled error when ODP is disabled and its features are requested.

Initialize the JavaScript (Browser) SDK with Real-Time Audiences and custom settings:

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

const optimizely = createInstance({
  sdkKey: 'YOUR_SDK_KEY',
  odpOptions: {
    // disabled: false,  // change to true to disable
    eventApiTimeout: 1000,
    eventQueueSize: 1,
    // eventRequestHandler: new BrowserRequestHandler(),
    // eventManager: new OdpEventManager(),
    segmentsApiTimeout: 1000,
    segmentsCacheSize: 10,
    segmentsCacheTimeout: 1000,
    // segmentsCache: new ICache<string, string[]>(),
    // segmentsRequestHandler: new BrowserRequestHandler(),
    // segmentManager: new OdpSegmentManager(),
  },
});

Note Unlike other SDKs, the JavaScript (Browser) cannot batch events. Because of that limitation, you cannot update the following:

eventBatchSize – Always set to 1.

eventFlushInterval – Always set to 0.

Call getVuid() after the client initializes

// After successfully initializing the JavaScript (Browser) SDK...
const deviceVuid = optimizely.getVuid();  
console.log('Device VUID: ${deviceVuid}');

For information, see VUIDs and client-side SDKsVUIDs and client-side SDKs.

Customize OdpManager

Using the parameters in odpOptions, you can customize the behavior of the ODP event and segment managers, even going as far as being able to replace them with your own implementations if desired.

Example odpOptions with Custom Event Manager

odpOptions: {
  // …
  eventManager: new OdpEventManager({
    odpConfig, // new OdpConfig()
    apiManager, // new OdpEventApiManager()
    logger, // new LogHandler()
    clientEngine: 'javascript-sdk',
    clientVersion: '5.0.0',
    batchSize: 10, // Cannot change in JavaScript (Browser) environment.
    flushInterval: 2000, // Cannot change in JavaScript (Browser) environment.
  }),
},

Customize OdpEventApiManager

Customizing the OdpEventApiManager requires you to provide an object with the following methods:

export interface IOdpEventApiManager {
  sendEvents(apiKey: string, apiHost: string, events: OdpEvent[]): Promise<boolean>;
}

Example odpOptions with Custom Segments Manager

odpOptions: {  
  // ...
  segmentManager: new OdpSegmentManager(  
    odpConfig, // new OdpConfig()  
    new BrowserLRUCache<string, string[]>({  
      maxSize: 2,  
      timeout: 4000,  
    }), // new ICache<string, string[]>()  
    segmentApiManager, // new IOdpSegmentApiManager()  
  ),  
},

Customize the OdpSegmentApiManage

export interface IOdpSegmentApiManager {  
  fetchSegments(  
    apiKey: string,  
    apiHost: string,  
    userKey: string,  
    userValue: string,  
    segmentsToCheck: string[]  
  ): Promise<string[] | null>;  
}

Custom cache

You can provide a custom cache, which is used to store the fetchQualifiedSegments results. To provide a custom cache, implement the following interface:

Segments Cache Interface

export interface ICache<K, V> {
  lookup(key: K): V | null;
  save({ key, value }: { key: K; value: V }): void;
  reset(): void;
}

Custom Segments Cache Implementation example from LRUCache implementation

export class LRUCache<K, V> implements ICache<K, V> {
  private _map: Map<K, CacheElement<V>> = new Map();
  private _maxSize; // Defines maximum size of _map
  private _timeout; // Milliseconds each entry has before it becomes stale

  get map(): Map<K, CacheElement<V>> {
    return this._map;
  }

  get maxSize(): number {
    return this._maxSize;
  }

  get timeout(): number {
    return this._timeout;
  }

  constructor({ maxSize, timeout }: LRUCacheConfig) {
    const logger = getLogger();

    logger.debug(`Provisioning cache with maxSize of ${maxSize}`);
    logger.debug(`Provisioning cache with timeout of ${timeout}`);

    this._maxSize = maxSize;
    this._timeout = timeout;
  }

  public lookup(key: K): V | null {
    if (this._maxSize <= 0) {
      return null;
    }

    const element: CacheElement<V> | undefined = this._map.get(key);

    if (!element) return null;

    if (element.is_stale(this._timeout)) {
      this._map.delete(key);
      return null;
    }

    this._map.delete(key);
    this._map.set(key, element);

    return element.value;
  }

  public save({ key, value }: { key: K; value: V }): void {
    if (this._maxSize <= 0) return;

    const element: CacheElement<V> | undefined = this._map.get(key);
    if (element) this._map.delete(key);
    this._map.set(key, new CacheElement(value));

    if (this._map.size > this._maxSize) {
      const firstMapEntryKey = this._map.keys().next().value;
      this._map.delete(firstMapEntryKey);
    }
  }

  public reset(): void {
    if (this._maxSize <= 0) return;

    this._map.clear();
  }

  public peek(key: K): V | null {
    if (this._maxSize <= 0) return null;

    const element: CacheElement<V> | undefined = this._map.get(key);

    return element?.value ?? null;
  }
}

An additional dependency was added to the Optimizely client's readyPromise promise resolution dependency array which resolves based on the success of initializing the VuidManager using localStorage.

Source files

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