Client-side implementation tips for the JavaScript SDK v6+

❗️

Warning

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

The datafile is a JSON representation of your Feature Experimentation project configuration (OptimizelyConfig) in a given environment. You can manage the datafile in several ways when using the JavaScript SDK client side.

Version

v6.0.0+

For versions 5.3.5 and below, see JavaScript (Browser) SDK. See the SDK compatibility matrix documentation for a list of current SDK releases and the features they support.

Include datafile as a synchronous script tag

This approach lets you include the datafile as a script that defines a global variable, window.optimizelyDatafile, containing the datafile contents.

Include the script tag before your application code that creates the Optimizely client instance. Replace YOUR_ENVIRONMENT_SDKKEY with your SDK key.

<script src="https://cdn.optimizely.com/datafiles/YOUR_ENVIRONMENT_SDKKEY.json/tag.js"></script>

In your application code, create the client instance using the global variable, like the following:

<script>  
    const {
      createStaticProjectConfigManager,
      createBatchEventProcessor,
      createOdpManager,
    } = window.optimizelySdk;
  
    const SDK_KEY="YOUR_SDK_KEY";
  
    const staticConfigManager = createStaticProjectConfigManager({
      datafile:window.optimizelyDatafile
    })
  
    const optimizelyClient  = window.optimizelySdk.createInstance({
      projectConfigManager:staticConfigManager,
    });
</script>

Pros

• Loads the most up-to-date datafile content.
• Prevents content flicker by using a blocking request.

Con

• Introduces slight page load latency due to the blocking request.

Synchronize the datafile between client and server

Use this approach if your organization already uses the Feature Experimentation SDK on the server. See Multiple Languages.

Pro

• Reduces flicker – Embedding the datafile inline prevents waiting on XHR fetch.
• Improves performance – Fewer requests during page load result in faster rendering.

Con

• Requires server-side logic to fetch and serve the datafile.

Bundle datafile in with Optimizely Feature Experimentation script

Use this approach with the XHR and localStorage cache strategy.

Bundle the datafile with a Feature Experimentation script in the following use cases:

• You need offline support or use service workers for aggressive caching.
• Your experiments do not change frequently.
• Your QA and engineering teams coordinate deployments and experiment launches.

Pro

• Provides offline access to the datafile.

Con

• Prevents real-time updates to the datafile.
• Should not be the only solution, since experiment changes are not propagated.

Fetch datafile with XHR

This approach offers the freshest datafile content. Use it with localStorage caching.

Pro

• Does not require server-side datafile management.
• Always retrieves the latest datafile from cdn.optimizely.com.

Con

• Causes a flicker on initial load due to asynchronous fetch.

📘

Note

If you use XHR to fetch the, you must defer the datafile load until after page load. This is ideal for page performance because it does not affect page load latency.

When using this approach you must complete the following:

• Instantiate a single client instance with a single datafile per visitor session.
• Persist the datafile contents in localStorage.
• Use the datafile contents fetched after page load and cached to localStorage only on subsequent page visits or sessions.

Load datafile contents using Edge Side Includes

This approach minimizes flicker with a one-time configuration. It requires one-time Edge Side Includes (ESI) configuration and does not require server-side datafile management service.

It does require a CDN vendor that supports ESI, such as Fastly or Akamai.

Pro

• Embeds the datafile directly in the page source.
• Eliminates client-side fetch requests.
• Requires only one-time configuration.

Con

• May present challenges for local or lower-level environments. ESI is a CDN feature, so you need a solution in place to serve the datafile when developing locally.

Fetch datafile with automatic datafile management

This built-in feature handles datafile fetching and updates automatically. This approach offers an easy implementation with good datafile freshness.

Pro

• Fetches directly from cdn.optimizely.com, no server-side logic is required.
• Offers a fast and simple implementation. No need to write datafile management code.
• Always uses the latest datafile content.
• Avoids blocking requests that delay page load.

Con

• Asynchronous. Must wait for datafile fetch.
• Can not use localStorage caching for fast synchronous initialization.

User identifiers

Use one of the following methods to obtain user identifiers (IDs).

• (Recommended) Use client-side analytics IDs from a client-side analytics service such as Google Analytics Client ID or Adobe Analytics Visitor ID. These IDs are generated asynchronously, so first-time visitors may not have a unique IDs on their first page view.
• Use cookies to store unique visitor IDs.

Link-click tracking

The Feature Experimentation JavaScript SDK does not use localStorage and consequently does not maintain a queue of pendingEvents (which Optimizely Web Experimentation does automatically). As a result, link-click tracking may fail if the user navigates away before the event is sent.

To avoid this, pass a tracking parameter in the URL and fire the event on the destination page.

Avoid reserved word for Optimizely Web Experimentation

If you use both Optimizely Web Experimentation and Optimizely Feature Experimentation client-side, then avoid the reserved word optimizely in your window-scoped variable names in Feature Experimentation. This word is reserved for Optimizely Web Experimentation, and using it in your Optimizely Feature Experimentation code can cause problems for Optimizely Web Experimentation, such as breaking the visual editor.

// Name your client-side Optimizely Feature Experimentation instance something like the following:
const optimizelyClientInstance = optimizelySDK.createInstance({
	projectConfigManager: projectConfigManager
});

// AVOID naming your client-side instance like the following:
const optimizely = optimizelySDK.createInstance({
	projectConfigManager: projectConfigManager
});

React and React Native SDKs

The Feature Experimentation React SDK simplifies integration with client-side and server-side React applications. See React SDK and React Native SDK.