Add listener

You can use the addListener API to listen for specific lifecycle events during the execution of the Optimizely Web Experimentation snippet.

Use this API to trigger custom code when important events occur, such as when the snippet initializes, activates a page, or assigns a visitor to a variation.

Listeners must be registered by pushing an addListener object onto the window["optimizely"] array.
If you want to remove a listener later, you must provide a token when adding the listener.

Use listeners to integrate Optimizely lifecycle events with your custom logic, analytics tools, or dynamic site behavior.

Syntax

window["optimizely"].push(addListener);

Parameters

Example call

window["optimizely"].push({
  "type": "addListener",
  "filter": {
    "type": "lifecycle",
    "name": "initialized"
  },
  "handler": function(event) {
    console.log("Project " + window["optimizely"].get("data").projectId + " is initialized");
  }
});

Description

Listen to a specific event from somewhere in the snippet's execution. For example, you can listen to the initialized event if you want to use the window.optimizely.get APIs as soon as they become available, or you can listen to the pageActivated event if you want to run code every time a page activates.

Your handler function is invoked for each applicable lifecycle event that occurs after the handler is registered. It is not retroactively invoked for events that may have occurred prior to handler registration.

Remove a listener

If you want to remove a listener after it is registered, you must provide a token when you add the listener. The token acts as an identifier that you can use to remove that specific listener later.

Add a listener with a token

When you add a listener, include a token field with a unique string value:

function onInitialized(event) {
  console.log("Project " + window["optimizely"].get("data").projectId + " is initialized");
}

window["optimizely"] = window["optimizely"] || [];
window["optimizely"].push({
  type: "addListener",
  filter: {
    type: "lifecycle",
    name: "initialized"
  },
  token: "UniqueListenerToken", // Replace with your token
  handler: onInitialized
});

📘

Note

If you do not provide a token when you add a listener, you cannot reference and remove that listener later.

Remove a listener with a token

When you want to remove the listener, call push again with the removeListener type and the same token.

window["optimizely"].push({
  type: "removeListener",
  token: "myUniqueListenerToken" // Replace with your token
});

initialized

Fires once the JavaScript API has been initialized.

Syntax

var initialized = function(initialized);

Parameters

Example call

function onInitialized(event) {
  console.log("Project " + window["optimizely"].get("data").projectId + " is initialized");
}

window["optimizely"] = window["optimizely"] || [];
window["optimizely"].push({
  type: "addListener",
  filter: {
    type: "lifecycle",
    name: "initialized"
  },
  handler: onInitialized
});

Description

By this point, the Optimizely Web Experimentation snippet has processed all window.optimizely.push API calls that were made before the snippet began to execute or during Project JavaScript.

window.optimizely.get is now defined in addition to window.optimizely.push, although visitor-specific state data (such as that returned by get('visitor') and get('state').getCampaignStates()) may not have been determined yet. See Get.

The snippet only initializes once per browser page load.

action.applied

Fires when some action (set of changes) has been applied.

Syntax

var actionApplied = function(actionAppliedEvent);

Parameters

Example call

function onActionApplied(event) {
  console.log("Applied action for Campaign:", event.data.campaignId);
}

window.optimizely.push({
  "type": "addListener",
  "filter": {
    "type": "action",
    "name": "applied"
  },
  "handler": onActionApplied
});

Description

After the Optimizely Web Experimentation snippet has decided on a variation for a particular campaign or experiment, it delivers the experience as a set of "actions". Each action is specific to a variation (for most changes) or experiment (for Shared Code and Shared CSS, and may be specific to a page.

Use this lifecycle event to detect when actions have been applied. Your handler can inspect the event payload to distinguish between the various actions that may be applied during the current page load.

📘

Note

The snippet may reapply an action's changes after the corresponding lifecycle event has fired, if elements relevant to a particular change appear at different times rather than all at once. This is particularly likely if you are using Optimizely Web Experimentation on a dynamic website.

activated

Fires each time the Optimizely Web Experimentation snippet activates.

Syntax

var activated = function(activated);

Parameters

Example call

function onActivated(event) {
  var visitorId = window.optimizely.get('visitor_id').randomId;
  console.log("The visitor's ID is: " + visitorId);
}

window["optimizely"] = window["optimizely"] || [];
window["optimizely"].push({
  type: "addListener",
  filter: {
    type: "lifecycle",
    name: "activated"
  },
  handler: onActivated
});

Description

At this point, the Optimizely Web Experimentation snippet has been activated, and you can query for visitor states such as the following:

• Visitor ID.
• Page states. A page is marked isActive if it was synchronously triggered
  by
  • an immediate trigger.
  • a URL change or DOM change trigger. (These triggers fire immediately during snippet activation, not just when the URL or DOM changes.)
  • a callback trigger, if its conditional activation code synchronously invokes the callback.
  • a manual trigger, if the corresponding JavaScript API was called before snippet activation and was found to have passing conditions.
• Campaign states and experiment states, for campaigns and experiments that
  1. specify changes to active Pages (see above), and
  2. target audiences that the snippet was able to evaluate using data it already had on hand, without waiting for the browser to download additional data.

The snippet activates immediately upon snippet initialization, but also reactivates each time the activate API is called.

campaignDecided

Fires each time the visitor is assigned a variation (or none) for a campaign or experiment.

Syntax

var campaignDecided = function(campaignDecided);

Parameters

Example call

function onCampaignDecided(event) {
  console.log("The visitor is now seeing variation " + event.data.decision.variationId + " of campaign " + event.data.campaign.name);
}

window["optimizely"] = window["optimizely"] || [];
window["optimizely"].push({
  type: "addListener",
  filter: {
    type: "lifecycle",
    name: "campaignDecided"
  },
  handler: onCampaignDecided
});

Description

Each time the Optimizely Web Experimentation snippet activates a campaign or experiment, the snippet decides which variation (if any) to serve to the current visitor and then fires a campaignDecided event.

Any Web events triggered by your handler function attributes to the variation that the visitor has just been assigned to, in addition to previously served variations.

If you want to track decisions in an external analytics platform, we recommend that you create a custom analytics integration instead of using this API directly. Custom analytics integrations are easier to configure and, unlike this API, can be used to track redirect decisions.

pageActivated

Fires each time a page becomes active.

Syntax

var pageActivated = function(pageActivated);

Parameters

Example call

function onPageActivated(event) {
  console.log("The Page " + event.data.page.name + " is now active");
}

window["optimizely"] = window["optimizely"] || [];
window["optimizely"].push({
  type: "addListener",
  filter: {
    type: "lifecycle",
    name: "pageActivated"
  },
  handler: onPageActivated
});

Description

This event indicates when a page has become active.

In some cases, a page may activate during snippet activation, while in other cases activation may occur after snippet activation or not at all.

This event may fire before or after the snippet applies the page-specific changes specified by active variations.

pageDeactivated

Fires each time a page is deactivated.

Syntax

var pageDeactivated = function(pageDeactivated);

Parameters

Example call

function onPageDeactivated(event) {
  console.log("The Page " + event.data.page.name + " is no longer active");
}

window["optimizely"] = window["optimizely"] || [];
window["optimizely"].push({
  type: "addListener",
  filter: {
    type: "lifecycle",
    name: "pageDeactivated"
  },
  handler: onPageDeactivated
});

Description

This event indicates when a page has been deactivated.

This event may fire before or after the snippet undoes the page-specific changes specified by active variations (if the Undo Changes setting is on for this page).

originsSynced

Fires when visitor data has been loaded from other origins.

Syntax

var originsSynced = function(originsSynced);

Parameters

Example call

function onOriginsSynced() {
  console.log("Cross-origin data is now synced.");
}

window["optimizely"] = window["optimizely"] || [];
window["optimizely"].push({
  type: "addListener",
  filter: {
    type: "lifecycle",
    name: "originsSynced"
  },
  handler: onOriginsSynced
});

Description

During snippet initialization, Optimizely Web Experimentation tries to fetch data that has been saved for the current visitor ID under other origins' localStorage. Such data may exist if the visitor has previously used the current web browser to visit other origins on which you are running Optimizely Web Experimentation snippets.

This operation is asynchronous and may complete after the initial snippet activation (unless you use the waitForOriginSync API to delay that snippet activation). The originsSynced event indicates when this operation has succeeded or failed. You may want to wait for this event before executing logic that preferably sees data from all your origins.

After the originsSynced event, syncing continues until the page unloads, but you do not receive any more notifications.

As a security precaution, the snippet only syncs data between origins that you have listed in your account settings.

For information, see Cross-origin tracking in Optimizely Web Experimentation.

trackEvent

Fires whenever a Web event has occurred.

Syntax

var trackEvent = function(trackEvent);

Parameters

Example call

function onTrackEvent(event) {
  console.log("The event " + event.data.name + " was tracked");
}

window["optimizely"] = window["optimizely"] || [];
window["optimizely"].push({
  type: "addListener",
  filter: {
    type: "analytics",
    name: "trackEvent"
  },
  handler: onTrackEvent
});

Description

The trackEvent lifecycle event is fired whenever the visitor triggers an Web event.

You can use this API if you want to track conversions in an external analytics platform.

You can also use this to manually activate a campaign or experiment after a particular event has occurred. For more complex targeting, you can use behavioral audiences or the get('behavior') API if you have access to Optimizely Web Personalization.