Initialize the JavaScript SDK v6

❗️

Warning

This content covers the Feature Experimentation JavaScript (Browser) SDK v6 features currently in pre-production testing and is subject to change before release

For the latest released version, see 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 the Decide methods. Each client corresponds to the datafile, representing the state of a project for a certain environment.

Minimum SDK version

v6.0.0+

Description

The createInstance method accepts a configuration object to configure the Optimizely client instance.

Some parameters are optional, you can opt in to use those features by providing the relevant configuration. For example, you can configure 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 following parameters are the required and optional properties of the configuration object:

Returns

Returns an instance of the Client interface.

Examples

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

1. Go to Settings > Environments.
2. Copy and save the SDK Key for your environment.

import {
  createBatchEventProcessor,
  createInstance,
  createOdpManager,
  createPollingProjectConfigManager,
} from "@optimizely/optimizely-sdk";

const SDK_KEY="YOUR_SDK_KEY";

const pollingConfigManager = createPollingProjectConfigManager({
  sdkKey: SDK_KEY,
  autoUpdate: true,
  updateInterval: 60000, // 1 minute
});

const batchEventProcessor = createBatchEventProcessor();
const odpManager = createOdpManager();

const optimizelyClient = createInstance({
  projectConfigManager: pollingConfigManager,
  eventProcessor: batchEventProcessor,
  odpManager: odpManager,
});

if (!optimizelyClient) {
  // There was an error creating the Optimizely client
} else {
  optimizelyClient
    .onReady()
    .then(() => {
      console.log("Client is ready");
      // Do something
    })
    .catch((err) => {
      console.error("Error initializing Optimizely client:", err);
      // Handle error
    });
}

<script src="https://unpkg.com/@optimizely/optimizely-sdk/dist/optimizely.browser.umd.min.js"></script>
 <!--this adds the datafile on the window variable window.optimizelyDatafile!-->
<script src="https://cdn.optimizely.com/datafiles/<YOUR_SDK_KEY>.json/tag.js"></script>

<script>
    const {
      createPollingProjectConfigManager,
      createBatchEventProcessor,
      createOdpManager,
    } = window.optimizelySdk;
  
    const SDK_KEY="YOUR_SDK_KEY";

    const pollingConfigManager = createPollingProjectConfigManager({
      sdkKey: SDK_KEY,
      datafile: window.optimizelyDatafile
      autoUpdate: true,
      updateInterval: 60000, // 1 minute
    });

    const batchEventProcessor = createBatchEventProcessor();
    const odpManager = createOdpManager();
  
    const optimizelyClient  = window.optimizelySdk.createInstance({
      projectConfigManager: pollingConfigManager,
      eventProcessor: batchEventProcessor,
      odpManager: odpManager,
    });
  
  	if (!optimizelyClient) {
  		// There was an error creating the Optimizely client
    } else {
      optimizelyClient
        .onReady()
        .then(() => {
          console.log("Client is ready");
          // Do something
        })
        .catch((err) => {
          console.error("Error initializing Optimizely client:", err);
          // Handle error
        });
    }
</script>

onReady method

onReady returns a promise that fulfills when this instance is ready to use (meaning it has a valid datafile), or rejects when it has failed to become ready within a period of time (configurable by the timeout property of the options argument), or when this instance is closed via the close method before it became ready.

If a static project config manager with a valid datafile was provided in the constructor, the returned Promise is immediately fulfilled. If a polling config manager was provided, it will be used to fetch a datafile, and the returned promise will fulfil if that fetch succeeds, or it will reject if the datafile fetch does not complete before the timeout. The default timeout is 30 seconds.

The returned Promise is fulfilled with an unknown result which does not need to be inspected to know that the instance is ready. If the promise is fulfilled, it is guaranteed that the instance is ready to use. If the promise is rejected, it means the instance is not ready to use, and the reason for the promise rejection will be an error denoting the cause of failure.

Project Config Manager

The Project Config Manager is responsible for managing the project configuration of an Optimizely client instance. It is a required component for creating a client instance. You can choose between two types of Project Config Managers:

1. Polling project config manager
2. Static project config manager

Polling Project Config Manager

This regularly polls the configuration at a specified interval (default is 5 mints).

import { createPollingProjectConfigManager, createInstance } from "@optimizely/optimizely-sdk";

const SDK_KEY = "YOUR_SDK_KEY"

const pollingConfigManager = createPollingProjectConfigManager({
  sdkKey: SDK_KEY,
  autoUpdate: true,
  updateInterval: 60000
});

const optimizelyClient = createInstance({
  projectConfigManager: pollingConfigManager
});

if (!optimizelyClient) {
  // There was an error creating the Optimizely client
} else {
  optimizelyClient
    .onReady()
    .then(() => {
      console.log("Client is ready");
      // Do something
    })
    .catch((err) => {
      console.error("Error initializing Optimizely client:", err);
      // Handle error
    });
}

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 download before using the instance.

To customize the behavior of the polling config manager you can use following options of PollingConfigManagerConfig -

Static Project Config Manager

Uses the provided datafile and does not perform any network requests to fetch or update the configuration.

import { createInstance, createStaticProjectConfigManager } from "@optimizely/optimizely-sdk";

const SDK_KEY="YOUR_SDK_KEY";

const fetchDatafile = async () => {
  const response = await fetch(
    `https://cdn.optimizely.com/datafiles/${SDK_KEY}.json`
  );
  if (!response.ok) {
    throw new Error(`Failed to fetch datafile: ${response.statusText}`);
  }
  
  const datafile = await response.json();
  
  return datafile;
};

const staticConfigManager = createStaticProjectConfigManager({
  datafile: datafile
})

const optimizelyClient = createInstance({
  projectConfigManager: staticConfigManager
});

if (!optimizelyClient) {
  // There was an error creating the Optimizely client
} else {
  optimizelyClient
    .onReady()
    .then(() => {
      console.log("Client is ready");
      // Do something
    })
    .catch((err) => {
      console.error("Error initializing Optimizely client:", err);
      // Handle error
    });
}

To customize the behavior of the static config manager you can use following options of StaticConfigManagerConfig -

Event Processor

Event processor can be used to process decision event or conversion event . Optimizely provides two types of Event Processors out of the box.

1. Batch Event Processor
2. Forwarding Event Processor

Batch Event Processor

The Batch Event Processor queues events and sends them in batches, improving performance by reducing network calls. You can configure the batch size, flush interval, and customize how events are dispatched or stored.

import {
  createInstance,
  createPollingProjectConfigManager,
  createBatchEventProcessor
} from "@optimizely/optimizely-sdk";

const batchEventProcessor = createBatchEventProcessor({
  batchSize: 5, // default is 10
  flushInterval: 10000, // default is 1000ms
});

To customize the behavior of the Batch Event Processor you can use following options of BatchEventProcessorOptions.

Forwarding Event Processor

The Forwarding Event Processor sends events immediately using the provided Event Dispatcher, without batching or queuing. It's a simple, low-latency option ideal for scenarios where events need to be dispatched immediately.

import { createInstance, createForwardingEventProcessor } from "@optimizely/optimizely-sdk";

const SDK_KEY="YOUR_SDK_KEY";

const pollingConfigManager = createPollingProjectConfigManager({
  sdkKey: SDK_KEY,
});

const forwardingEventProcessor = createForwardingEventProcessor()

const optimizelyClient = createInstance({
  projectConfigManager: pollingConfigManager,
  eventProcessor: forwardingEventProcessor
});

To customize the behavior of the Forwarding Event Processor you can use following options -

ODP Manager

ODP Manager contains the logic supporting Real-Time Segments for Feature Experimentation-related features, including audience segments, ODP events, and VUID tracking.

To enable Real-time Segments for Feature Experimentation you have to pass the OdpManager and configure Real-Time Segments for Feature Experimentation.

import { createInstance, createOdpManager } from "@optimizely/optimizely-sdk";

const SDK_KEY="YOUR_SDK_KEY";

const pollingConfigManager = createPollingProjectConfigManager({
  sdkKey: SDK_KEY,
});

const odpManager = createOdpManager({
  eventApiTimeout: 1000,
  segmentsApiTimeout: 1000,
  segmentsCacheSize: 10,
  segmentsCacheTimeout: 1000,
  eventBatchSize: 5,
  eventFlushInterval: 3000,
});

const optimizelyClient = createInstance({
  projectConfigManager: pollingConfigManager,
  odpManager: odpManager
});

To customize the behavior of the ODP Manager you can use following options of OdpManagerOptions.

VUID Manager

ODP uses various identifiers unique to a specific customer to track their data. One such identifier is the VUID, which is associated with a specific device. Since VUID tracking is opt-in, it will only be used if a VUID manager is provided during instantiation. Additionally, if enableVuid: false is specified when creating the VUID manager, any previously stored VUID-related data on the device will be cleared.

import {
  createInstance,
  createPollingProjectConfigManager,
  createBatchEventProcessor,
  createOdpManager,
  createVuidManager
} from "@optimizely/optimizely-sdk";


const pollingConfigManager = createPollingProjectConfigManager({
  sdkKey: "<YOUR_SDK_KEY>",
})

const batchEventProcessor = createBatchEventProcessor()

const odpManager = createOdpManager()

const vuidManager = createVuidManager({
  enableVuid: true
});


const optimizelyClient = createInstance({
  projectConfigManager: pollingConfigManager,
  eventProcessor: batchEventProcessor,
  odpManager: odpManager,
  vuidManager: vuidManager,
});

To customize the behavior of the VUID Manager you can use following options of VuidManagerOptions.

Dispose of the client

close method

For effective resource management with the JavaScript (Browser) SDK, you must properly close the Optimizely client instance when it is no longer needed. You can do so by calling optimizely.close().

The .close() method ensures that the background tasks 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.

disposable config

It's also possible to make the instance of Optimizely client disposable by passing disposable: true in the config. All the background processing will be turned off (no datafile polling, no event batching) so that the instance can be garbage collected when all reference to it ceases to exist, event if close() method is not called. Without it, the SDK instance might not get garbage collected if close() method is not called. This is particularly beneficial in situations where an instance of the SDK is created per request, and explicitly calling close() on the instances are inconvenient/impossible. (E.g. SSR, Edge environments etc)

See Close Optimizely Feature Experimentation JavaScript SDK on application exit.

Source files

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