Client-side implementation tips for the JavaScript (Browser) SDK

Contact support or your Customer Success Manager if you need help with your implementation.

Datafile management for JavaScript client-side implementation

The datafile is a JSON representation of your Feature Experimentation project configuration (OptimizelyConfig) in a given environment. The following sections describe different options for managing the datafile:

Include datafile as a synchronous script tag

This approach allows you to include the datafile as a script. The script will define a global variable, window.optimizelyDatafile, that contains the datafile contents.

Include the datafile script tag above your app code that creates a new Optimizely client instance:

<script src="https://cdn.optimizely.com/datafiles/[YOUR ENVIRONMENT SDKKEY].json/tag.js"></script>

In your app code, reference that variable when creating a new Optimizely client instance:

<script>  
var optimizelyClientInstance = window.optimizelySdk.createInstance({
  datafile: window.optimizelyDatafile
});
</script>

Synchronize the datafile between client and server

Consider this approach if your organization is already using the Optimizely Feature Experimentation SDK on the server side. For more information, see Multiple Languages.

Bundle datafile in with Optimizely Feature Experimentation script

Optimizely recommends using this approach in conjunction with the XHR and localStorage cache approach.

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

• You need a fallback for offline web applications or web applications that are heavily cached with service workers.
• Your organization will not perform many in-flight experiment updates.
• The test team can coordinate the experiment start with the client-side build and deploy team.

Fetch datafile using XHR

This approach offers the best datafile freshness. Use this approach in conjunction with localStorage datafile caching.

📘

Note

If you fetch the datafile using XHR, Optimizely recommends that you 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:

• Make sure to instantiate a client instance with a single datafile across a 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 (ESI)

This approach is best for minimizing page flicker. It only requires one-time ESI setup and does not require server-side datafile management service.

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

Fetch datafile using automatic datafile management

You can implement the automatic datafile management functionality to handle datafile updates. This approach offers an easy implementation with good datafile freshness.

User identifiers

To obtain user identifiers (IDs), use one of these methods:

• Recommended – Use IDs from a client-side analytics service like Google Analytics Client ID or Adobe Analytics Visitor ID. Because these IDs are generated asynchronously, a first-time visitor probably will not have a unique IDs on their first page view.
• Use cookies with unique visitor IDs.

Link-click tracking

The Optimizely Feature Experimentation JavaScript SDK does not use localStorage and consequently does not maintain a queue of pendingEvents (which Optimizely Web Experimentation does automatically). This means the browser will likely cancel a number of link-click tracking calls as users are being redirected.

A possible solution is to pass a parameter to the subsequent page URL and fire an event on that page.

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 this:
const optimizelyClientInstance = optimizelySDK.createInstance({
	sdkKey: '<Your_SDK_Key>'
});

// AVOID naming your client-side instance this:
const optimizely = optimizelySDK.createInstance({
	sdkKey: '<Your_SDK_Key>'
});

React & React Native SDKs

Our React SDK simplifies integration with client-side and server-side React applications. See the README on GitHub for features, use cases, and implementation instructions.