Optimizely X Support for Dynamic Websites

Optimizely X offers a variety of options for supporting single-page applications and other dynamic websites. Different options may be preferable depending on your web application's architecture. Before reading further, we recommend reviewing this Knowledge Base article to become familiar with the relevant Optimizely concepts.

Page Activation

Begin by configuring Pages to reflect the logical views or components of your application. Pages are the where of Optimizely X. They're sections of your site where you'll modify the experience and track behavior. On a non-dynamic website, a Page logically maps to a document. On a dynamic website or single-page application, a Page should correspond to a section of your site that a visitor may consider a distinct experience.

You can use activation triggers and conditions to indicate when your views are active and need to be optimized. Triggers indicate when a Page's conditions should be checked, and conditions determine whether the Page should indeed be activated. A Page's conditions are checked each time its trigger fires.

Only one "instance" of a Page may be active at a time. If you would like to activate a Page multiple times in a given context, then you will need to deactivate it before activating it again.

Triggers

Triggers indicate when a Page's conditions should be checked.

Immediate

The Immediate trigger fires when the Optimizely snippet activates. This is the default trigger.

URL Change

The URL Change trigger fires every time the URL changes, even if only the query string or hash has changed. This trigger also fires when the Optimizely snippet activates, for example upon initial page load.

Importantly, Optimizely uses a runtime patch of the History API to detect when the URL changes and fire the trigger.

This activation trigger only works if the snippet includes Support for Dynamic Websites.

DOM Change

The DOM Change trigger fires every time the DOM changes. This trigger also fires when the Optimizely snippet activates, for example upon initial page load.

Optimizely uses a MutationObserver to detect when an element is inserted, removed, or modified.

This activation trigger only works if the snippet includes Support for Dynamic Websites.

Callback

To perform Callback activation, you provide JavaScript that invokes a callback function when you are ready for the trigger to fire. Your JavaScript will often run before DOM ready, so you may want to use Optimizely's utility APIs to defer the callback until the relevant part of DOM is available for modification.

Your JavaScript runs unconditionally before the Page's conditions are checked. If you do not want code to be evaluated every time the snippet activates, you must wrap that code in an if statement that checks the URL or other conditions manually.

If you would like to use jQuery in your JavaScript, remember to use Optimizely's jQuery API: var $ = window.optimizely.get('jquery');

Parameters
Usage
// Poor usage.
function trigger(activate, options) {
  if (/* SOME CONDITION */) {
    document.querySelector('button').addEventListener('click', activate);
  }
}

// Better usage.
function trigger(activate, options) {
  var utils = window.optimizely.get('utils');

  utils.waitForElement('button').then(function(buttonElement) {
    buttonElement.addEventListener('click', activate);
  });
}

// Best usage.
function trigger(activate, options) {
  var utils = window.optimizely.get('utils');

  if (window.location.href.indexOf(/* Some URL */) !== -1) {
    utils.waitForElement('button').then(function(buttonElement) {
      buttonElement.addEventListener('click', function() {
        options.isActive && activate({isActive: false});
        activate();
      });
    });
  }
}

Note: In the "best usage" example above you'll see that we first check the options.isActive boolean to determine if the Page is already active in the given context, then we explicitly deactivate the Page with the optional isActive parameter should options.isActive return true. This usage allows you to reactivate this Page as many times as needed when a user clicks on the button element. For more usage examples please see the code samples section.

Polling

This trigger polls every 50ms for a JavaScript predicate to return true. The JavaScript function must always return a boolean value.

Polling for a specific element is a common use case. The trigger will stop polling 2 seconds after DOM ready, so for views that may take longer than 2 seconds to load, consider the DOM Change trigger or Callback trigger instead.

If you would like to use jQuery in your JavaScript, remember to use Optimizely's jQuery API: var $ = window.optimizely.get('jquery');

Usage
function pollingPredicate() {
  return document.querySelectorAll("div.btn-green").length > 0;
}

Manual

The Manual trigger fires when a page is pushed using the manual activation API.

Parameters
Usage
window.optimizely = window.optimizely || [];

// Basic Page activation. `isActive` param isn't necessary.
window.optimizely.push({
  type: "page",
  pageName: "checkout_stage_1"
});

// Basic Page deactivation. Must be done to reactivate "checkout_stage_1" again.
window.optimizely.push({
  type: "page",
  pageName: "checkout_stage_1",
  isActive: false
});

// Page activation with tags
window.optimizely.push({
  type: "page",
  pageName: "product_detail",
  tags: {
    category: "Kitchen",
    subcategory: "Blenders",
    price: 64999,
    sku: "113757"
  }
});

Conditions

When a Page's trigger has fired, the Page's conditions determine whether the Page should actually be activated. The Page activates if all conditions pass or if there are no conditions to check at all.

URL Match

Determines whether the visitor's URL matches a given rule. This is the default condition.

Element Present

Determines if a particular element exists in the DOM. We do this by calling document.querySelectorAll() on the provided CSS Selector.

JavaScript Condition

Determines whether a JavaScript predicate returns true.

Usage
function conditionFn() {
  return dataLayer.pageType === "category";
}

Optimizely Desktop Application

The desktop app is an Optimizely application that runs natively on your computer (Windows, MacOS or Linux). It allows you to connect to the Optimizely web application without using a browser. This can make editing experiments and campaigns quicker, less error-prone, and easier for single-page applications.

If your team is interested in using the Desktop Application please learn more here.

Full Stack SDKs

Optimizely X's Full Stack offering is also capable of working on Single Page Applications. You can find the SDK reference here.