The Full Stack Developer Guide Developer Hub

Welcome to the Full Stack Developer Guide developer hub. You'll find comprehensive guides and documentation to help you start working with the Full Stack Developer Guide as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Add listener

Listen to a snippet lifecycle event.

Syntax

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

Parameters

Parameter and Type
Child Attribute
Description

addListener
AddListenerObject

-

An object with the type field set to addListener. The other fields are the function arguments. Required.

type
string

Child attribute of type AddListenerObject

The argument indicating that you are using the addListener function. Required.

filter
FilterObject

Child attribute of type AddListenerObject

By setting a filter, you can define the type of events or category of events the handler is called for.

type
string
Required

Child attribute of type FilterObject

The category of an event. Possible values: lifecycle and analytics. Required.

name
string

Child attribute of type FilterObject

The name of the event type. The value can be initialized, applied, activated, campaignDecided, pageActivated, pageDeactivated, originsSynced, or trackEvent.

handler
function

Child attribute of type AddListenerObject

The function that will be called when the event occurs.

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 will be 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.

You can listen to the following types of events:

initialized

Fires once the JavaScript API has been initialized.

Syntax

var initialized = function(initialized);

Parameters

Parameter and Type
Child Attribute
Description

initialized
InitializedObject

-

This is the object passed to the handler function. Required.

type
string

Child attribute of type InitializedObject

The category of an event. The value will be lifecycle for this event. Required.

name
string

Child attribute of type InitializedObject

The name of the event type. This is set to initialized.

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 snippet will have processed all window.optimizely.push API calls that were made before the snippet began to execute or during Project JavaScript.

window.optimizely.get will now be 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.

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

Parameter and Type
Child Attribute
Description

actionAppliedEvent
ActionAppliedEvent

-

The data relevant to the action.applied event. Required.

type
string

Child attribute of type ActionAppliedEvent

The type of the event. Always "action" for this event. Required.

name
string

Child attribute of type ActionAppliedEvent

The name of the event. Always "applied" for this event. Required.

data
ActionAppliedEventData

Child attribute of type ActionAppliedEvent

Data about the event. Required.

changes
array[ChangeData]

Child attribute of type array[ChangeData]

List of changes that were attempted.

type
string

Child attribute of type ChangeData

Type of the change (e.g., "attribute", "code").

selector
string or undefined

Child attribute of type ChangeData

(For visual element-based changes only) Selector chosen in the editor.

attributes
object or undefined

Child attribute of type ChangeData

Change-specific attributes, such as the HTML attribute to modify, and the modified value.

type
string or function or undefined

Child attribute of type ChangeData

String value for "insert_html", "insert_image", and "custom_css". Function to execute if "custom_code".

campaignId
string

Child attribute of type ActionAppliedEvent

ID of campaign the action belongs to. Required.

pageId
string

Child attribute of type ActionAppliedEvent

ID of the page on which the action was executed. Required.

experimentId
string or undefined

Child attribute of type ActionAppliedEvent

ID of experiment the action belongs to, or undefined if campaign action.

variationId
string or undefined

Child attribute of type ActionAppliedEvent

ID of variation the action belongs to, or undefined if campaign or experiment action.

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 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're using Optimizely on a dynamic website.

activated

Fires each time the Optimizely snippet activates.

Syntax

var activated = function(activated);

Parameters

Parameter and Type
Child Attribute
Description

activated
ActivatedObject

-

This is the object passed to the handler function. Required.

type
string

Child attribute of type ActivatedObject

The category of an event. The value will be lifecycle for this event. Required.

name
string

Child attribute of type ActivatedObject

The name of the event type. This is set to activated.

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 snippet has been activated, and you can query query for visitor state such as:

  • Visitor ID.
  • Page states. A page will be 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 will also reactivate 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
Parameter and Type
Child Attribute
Description

campaignDecided
CampaignDecidedObject

-

The data relevant to the campaignDecided event. Required.

type
string

Child attribute of type CampaignDecidedObject

The category of an event. The value will be lifecycle for this event. Required.

name
string

Child attribute of type CampaignDecidedObject

The name of the event type. This is set to campaignDecided.

data
CampaignEventData

Child attribute of type CampaignDecidedObject

Data associated to this event. You can use this object to determine which campaign a decision was made for.

campaign
Campaign

Child attribute of type CampaignEventData

The complete campaign object.

changes
array[Change]

Child attribute of type Campaign

Changes on a campaign level. These changes are executed every time the campaign gets activated, regardless of the experiment and variation a visitor is assigned to.

*
string or integer

Child attribute of type Change

You can specify additional properties of your choice.

commitId
string

Child attribute of type Campaign

A new "commit" is made every time a campaign is published. The commit ID refers to the commit that was made. Every time a campaign is published, the commit ID changes.

experiments
array[Experiment]

Child attribute of type Campaign

An array of experiments within the campaign. For AB tests, there is always one experiment. Personalization Campaigns can have more experiments.

audienceIds
array[string,array]

Child attribute of type Experiment

Representation of audience conditions for the experiment, including audience IDs and combinators. See audience_conditions for format.

audienceName
string

Child attribute of type Experiment

Representation of name of audience(s) used in the experiment.

id
string

Child attribute of type Experiment

The ID of the experiment.

name
string

Child attribute of type Experiment

The name of the experiment.

integrationSettings
IntegrationObject

Child attribute of type Experiment

An object that contains all the integration settings that are enabled for this experiment. Each key in the object is mapped to a particular integration.

*
string or integer

Child attribute of type IntegrationObject

You can specify additional properties of your choice.

variations
array[Variation]

Child attribute of type Experiment

The variations within an experiment. There are one or more variations in an experiment.

actions
Action

Child attribute of type Variation

The actions that are executed once a visitor gets bucketed in this variation. The actions describe the variation.

pageId
string

Child attribute of type Action

The ID of the page where the action will take place.

changes
array[Change] or string

Child attribute of type Action

An array of changes that have been set up for this page.

*
string or integer

Child attribute of type Change

You can specify additional properties of your choice.

commitId
string

Child attribute of type Campaign

A new "commit" is made every time a campaign is published. The commit ID refers to the commit that was made. Every time a campaign is published, the commit ID changes.

experiments
array[Experiment]

Child attribute of type Campaign

An array of experiments within the campaign. For AB tests, there is always one experiment. Personalization Campaigns can have more experiments.

audienceIds
array[string,array]

Child attribute of type Experiment

Representation of audience conditions for the experiment, including Audience IDs and combinators. See audience_conditions for format.

audienceName
string

Child attribute of type Experiment

Representation of name of audience(s) used in experiment.

id
string

Child attribute of type Experiment

The ID of the experiment.

name
string

Child attribute of type Experiment

The name of the experiment.

integrationSettings
IntegrationObject

Child attribute of type Experiment

An object that contains all the integration settings that are enabled for this experiment. Each key in the object is mapped to a particular integration.

*
string or integer

Child attribute of type IntegrationObject

You can specify additional properties of your choice.

variations
array[Variation]

Child attribute of type Experiment

The variations within an experiment. There are one or more variations in an experiment.

actions
Action

Child attribute of type Variation

The actions that are executed once a visitor gets bucketed in this variation. The actions describe the variation.

pageId
string

Child attribute of type Action

The ID of the page where the action will take place.

changes
array[Change]

Child attribute of type Action

An array of changes that have been set up for this page.

*
string or integer

Child attribute of type Change

You can specify additional properties of your choice.

id
string

Child attribute of type Variation

The ID of the variation.

name
string

Child attribute of type Variation

The name of the variation.

weightDistributions
null or array[WeightDistributionsObject]

Child attribute of type Experiment

Traffic allocation among the variations in the experiment.

entityId
string

Child attribute of type WeightDistributionsObject

The ID of the variation that has the endOfRange value assigned to it.

endOfRange
integer

Child attribute of type WeightDistributionsObject

Each object in the array has a endOfRange value. The endOfRange of the current object minus the endOfRange object of the previous object is the traffic allocation assigned to the variation. The last object in the array always has a endOfRange value of 10000.

id
string

Child attribute of type Campaign

The ID of the campaign.

name
string

Child attribute of type Campaign

The name of the campaign.

holdback
integer

Child attribute of type Campaign

The holdback value on a campaign represents the percentage of visitors excluded from a campaign. If the holdback is set to 500, then 5% of all visitors are excluded from the campaign.

policy
string

Child attribute of type Campaign

The policy of a campaign indicates if the campaign is an AB test or a Personalization campaign. The possible values are:
"single_experiment": A normal AB test
"random": A Personalization campaign

integrationSettings
IntegrationObject

Child attribute of type Campaign

An object that contains all the integration settings that are enabled for this campaign.

*
string or integer

Child attribute of type IntegrationObject

You can specify additional properties of your choice.

pageIds
array[string]

Child attribute of type Campaign

An array with the IDs of all the pages that are used within the campaign.

decisionTicket
DecisionTicketObject

Child attribute of type CampaignEventData

The decision ticket.

audienceIds
array

Child attribute of type DecisionTicketObject

An array of audiences the visitor qualified for at the time of the decision.

bucketingId
string

Child attribute of type DecisionTicketObject

Optimizely unique end user ID used to bucket the visitor.

preferredVariationMap
object

Child attribute of type DecisionTicketObject

Contains a map of experiment ID to variation ID.

decision
DecisionObject

Child attribute of type CampaignEventData

The decision for this campaign. Required.

campaignId
string

Child attribute of type DecisionObject

The ID of the campaign the visitor is bucketed in.

experimentId
string

Child attribute of type DecisionObject

The ID of the experiment the visitor is bucketed in (if any).

isCampaignHoldback
Boolean

Child attribute of type DecisionObject

Property showing if a user has been included in the experiment based on the traffic allocation setting of the A/B experiment. For Personalization Campaigns, this property is based on the campaign holdback setting.

variationId
string

Child attribute of type DecisionObject

The ID of the variation the visitor is bucketed in (if any).

reason
string

Child attribute of type DecisionObject

The reason the visitor was not bucketed into a variation, e.g., "not eligible for any experiments".

error
Error

Child attribute of type DecisionObject

Any uncaught error encountered in the process of evaluating the decision. This could be indicative of a problem and should be reported to Optimizely support.

audiences
array[integer]

Child attribute of type CampaignEventData

The IDs of all the audiences in this campaign the visitor qualified for.

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 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 X Web events triggered by your handler function will attribute 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
Parameter and Type
Child Attribute
Description

pageActivated
PageActivatedObject

-

The data relevant to the pageActivated event. Required.

type
string

Child attribute of type PageActivatedObject

The category of an event. The value will be lifecycle for this event. Required.

name
string

Child attribute of type PageActivatedObject

The name of the event type. This is set to pageActivated.

data
PageEventData

Child attribute of type PageActivatedObject

Data associated to this event. You can use this object to determine which page has been activated.

page
Page

Child attribute of type PageEventData

The complete page object.

activationType
string

Child attribute of type Page

The trigger type that activates the page.

apiName
string

Child attribute of type Page

A machine-readable name for the page. The apiName value can be used in the page function to indicate which event has occurred.

category
string

Child attribute of type Page

An event category that was selected upon creation of the page. Some valid values for category are "added to cart", "saved", "shared", "searched", "purchased", "converted", "signed up", "subscribed", "other".

deactivationEnabled
Boolean

Child attribute of type Page

Whether or not this page is automatically deactivated when its trigger fires and conditions are false.

id
string

Child attribute of type Page

The page ID.

staticConditions
array

Child attribute of type Page

The conditions that need to be true for the page to be activated.

undoOnDeactivation
Boolean

Child attribute of type Page

Whether or not the changes for this page are undone when this page deactivates. Note that not all types of changes can be undone. Learn more.

tags
array[VisualTagObject]

Child attribute of type Page

An array of the visual tags saved on a page. Read more about visual tags.

category
string

Child attribute of type VisualTagObject

A tag category that was selected upon creation of the tag. Some valid values for category are: "category", "subcategory", "title", "price", "other".

locator
string

Child attribute of type VisualTagObject

The logic/CSS selector indicating where a tag is located on the page.

apiName
string

Child attribute of type VisualTagObject

A machine-readable name for the tag.

locatorType
string

Child attribute of type VisualTagObject

A enum that indicates if the locator is custom "javascript" or a "css_selector".

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
Parameter and Type
Child Attribute
Description

pageDeactivated
PageDeactivatedObject

-

The data relevant to the pageDeactivated event. Required.

type
string

Child attribute of type PageDeactivatedObject

The category of an event. The value will be lifecycle for this event. Required.

name
string

Child attribute of type PageDeactivatedObject

The name of the event type. This is set to pageDeactivated.

data
PageEventData

Child attribute of type PageDeactivatedObject

Data associated to this event. You can use this object to determine which page has been activated.

page
Page

Child attribute of type PageEventData

The complete page object.

activationType
string

Child attribute of type Page

The trigger type that activates the page.

apiName
string

Child attribute of type Page

A machine-readable name for the page. The apiName value can be used in the page function to indicate which event has occurred.

category
string

Child attribute of type Page

An event category that was selected upon creation of the page. Some valid values for category are "added to cart", "saved", "shared", "searched", "purchased", "converted", "signed up", "subscribed", "other".

deactivationEnabled
Boolean

Child attribute of type Page

Whether or not this page is automatically deactivated when its trigger fires and conditions are false.

id
string

Child attribute of type Page

The page ID.

staticConditions
array

Child attribute of type Page

The conditions that need to be true for the page to be activated.

undoOnDeactivation
Boolean

Child attribute of type Page

Whether or not the changes for this page are undone when this page deactivates. Note that not all types of changes can be undone. Learn more.

tags
array[VisualTagObject]

Child attribute of type Page

An array of the visual tags saved on a page. Read more about visual tags.

category
string

Child attribute of type VisualTagObject

A tag category that was selected upon creation of the tag. Some valid values for category are: "category", "subcategory", "title", "price", "other".

locator
string

Child attribute of type VisualTagObject

The logic/CSS selector indicating where a tag is located on the page.

apiName
string

Child attribute of type VisualTagObject

A machine-readable name for the tag.

locatorType
string

Child attribute of type VisualTagObject

A enum that indicates if the locator is custom "javascript" or a "css_selector".

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
Parameter and Type
Child Attribute
Description

originsSynced
OriginsSyncedObject

-

The name and type of the originsSynced event. Required.

type
string

Child attribute of type OriginsSyncedObject

The type of the event. The value will be lifecycle for this event. Required.

name
string

Child attribute of type OriginsSyncedObject

The name of the event. The value will be originsSynced for this event.

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 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're running Optimizely X Web 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 will continue until the page unloads, but you won't receive any more notifications.

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

For more information, see this article on cross-origin targeting.

trackEvent

Fires whenever an X Web event has occurred.

Syntax

var trackEvent = function(trackEvent);
Parameters
Parameter and Type
Child Attribute
Description

trackEvent
TrackEventObject

-

The data relevant to the trackEvent event. Required.

type
string

Child attribute of type TrackEventObject

analytics

name
string

Child attribute of type TrackEventObject

trackEvent

data
TrackEventData

Child attribute of type TrackEventObject

Data associated to this event. You can use this object to determine which event was triggered.

type
string

Child attribute of type TrackEventData

The type of the tracked event (e.g., "custom" for custom events, "pageview" for page-activated events).

name
string

Child attribute of type TrackEventData

The name of the tracked event.

apiName
string

Child attribute of type TrackEventData

The apiName of the tracked event. Note that for "pageview" events, this is the api_name of the page.

category
string

Child attribute of type TrackEventData

The category of the tracked event/page.

metrics
MetricData

Child attribute of type TrackEventData

Metrics attached to the event, if any.

revenue
number or undefined

Child attribute of type MetricData

Revenue value associated with the event, if any.

tags
Object

Child attribute of type TrackEventData

Map of tag name to tag value.

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 X 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 Personalization.

Updated about a year ago


Add listener


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.