Initialize the JavaScript SDK v6+

Returns

Returns an instance of the Client interface or throws an error if an invalid configuration is passed.

Examples

To instantiate using an SDK key, obtain the SDK Key from your project's settings 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,
});

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 through 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 is 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 the following two types of project config manager:

• Polling project config manager
• Static project config manager

Poll project config manager

This regularly polls the configuration at a specified interval (default is five minutes).

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
});

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.

See the following table to customize the behavior of the polling config manager using 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.text();
  
  return datafile;
};

const datafile = await fetchDatafile();

const staticConfigManager = createStaticProjectConfigManager({
  datafile
})

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


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 the following options of StaticConfigManagerConfig:

Event processor

The event processor can be used to process decision event or conversion event. Optimizely provides two types of event processors.

• Batch event processor
• 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,
  flushInterval: 10000,
});

To customize the behavior of the batch event processor you can use the following options of BatchEventProcessorOptions:

Forward event processor

The forwarding event processor sends events immediately using the provided event dispatcher, without batching or queuing. It is a simple, low-latency option ideal for scenarios where events need to be dispatched immediately. This is also a good choice if you want to employ your own logic to event processing, in which case you can use a custom event dispatcher with a forwarding event processor, which will just forward all events to your custom dispatcher.

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 the following options:

OdpManager

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

To enable Real-time Audiences for Feature Experimentation you have to pass the OdpManager and configure Real-Time Audiences 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 OdpManager you can use the 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 is only 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 is 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 the following options of VuidManagerOptions:

Dispose of the client

close method

For effective resource management with the JavaScript 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 is also possible to make the instance of Optimizely client disposable by passing disposable: true in the config. All the background processing is turned off (no datafile polling, no event batching) so that the instance can be garbage collected when all reference to it ceases to exist, even if the close() method is not called. Without it, the SDK instance might not get garbage collected if the 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 or impossible (for example, server-side rendering, edge environments, and so on).

See Close Optimizely Feature Experimentation JavaScript SDK on application exit.

Source files

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