Client-side implementation tips

This topic describes tips and considerations for installing Optimizely Full Stack JavaScript on a client (browser) instead of a server.

Please contact support if you need help with your implementation.

Datafile management for JavaScript client-side implementation

The datafile is a JSON representation of your Full Stack 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>

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 Optimizely SDK on the server side. For more information, see Multiple Languages .

Pro

Con

  • Mitigates flickering scenarios: If the datafile contents live inline in the page source, the client instantiation doesn’t 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 Full Stack script

We recommend using this approach in conjunction with the XHR and localStorage cache approach.

Bundle the datafile with a Full Stack 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 won't 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 won't propagate to visitors (for example, experiment pausing and other configurations).

Fetch datafile via XHR

This approach offers the best datafile freshness. Use this approach in conjunction 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’re fetching the datafile.

📘

Note

If you fetch the datafile via XHR, we recommend that you defer the datafile load until after page load. This is ideal for page performance because it doesn’t 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 via Edge Side Includes (ESI)

This approach is best for minimizing page flicker. It only requires one-time ESI setup and doesn't 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't 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 won’t have a unique IDs on their first page view.
  • Use cookies with unique visitor IDs.

Link-click tracking

The Optimizely JavaScript SDK doesn’t use localStorage and consequently doesn’t maintain a queue of pendingEvents (which Optimizely X Web 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.

Reserve word for Optimizely Web

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

// name your client-side Optimizely 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 for features, use cases, and implementation instructions.


Did this page help you?