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

12 min

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 lets you 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>

Pro	Con
Always uses the most up-to-date datafile contents. Blocking request; no flickering.	Blocking request introduces slight page-load latency.

Synchronize the datafile between client and server

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

Pro	Con
Mitigates flickering scenarios – If the datafile contents live inline in the page source, the client instantiation does not have to wait until the XHR fetch is complete. Better performance – Fewer requests during page load results in faster page rendering (first meaningful paint).	Must build a server-side solution for capturing fresh datafiles and persisting them to the client side.

Bundle datafile in with the Optimizely script

You should using this approach with the XHR and localStorage cache approach.

Bundle the datafile with the Optimizely 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.

Pro	Con
Datafile is available while the app is offline.	Cannot update datafile contents. Cannot use this approach as the sole solution: Experiment updates will not propagate to visitors (for example, experiment pausing and other configurations).

Fetch datafile using XHR

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

Pro	Con
No need for server-side datafile management. Fetch directly from the client side to cdn.optimizely.com. Will always have the most up-to-date datafile contents.	Asynchronous. Will cause a flicker when trying to test on the same page you are fetching the datafile.

Note If you fetch the datafile using XHR, You should 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:

Ensure you 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.

Pro	Con
Datafile contents inline in page source. No request needed on the client side. One-time setup.	May present challenges for lower-level environments. ESI is a CDN feature, so you need a solution in place to serve the datafile when developing locally.

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.

Pro	Con
No need for server-side datafile management. Fetch directly to the client side from cdn.optimizely.com. Fast implementation: no need to write datafile management code. Will always have the most up to date datafile contents. No blocking request that affects page load.	Asynchronous. Must wait for datafile fetch. Can not use localStorage caching for fast synchronous initialization.

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 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 ExperimentationOptimizely Web Experimentation and 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 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

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