HomeGuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog In

State

Returns a module exposing several functions to access information about the current visitor's state.

Syntax

state = window["optimizely"].get("state");

Parameters

Parameter and TypeChild AttributeDescription
state
string
N/AThe argument indicating to get the state object. Required.

Return value

Parameter and TypeChild AttributeDescription
StateObjectN/AThe object contains functions to get more information about the current state of Optimizely Web Experimentation.
getActiveExperimentIds
function[getActiveExperimentIds]
Child attribute of type StateObjectGet an array of experiment IDs that are currently active on the page for the visitor.
getCampaignStates
function[getCampaignStates]
Child attribute of type StateObjectGet all the campaigns and their current states.
getExperimentStates
function[getExperimentStates]
Child attribute of type StateObjectGet all the experiments and their current states.
getPageStates
function[getPageStates]
Child attribute of type StateObjectGet all the pages and their current states.
getRedirectInfo
function[getRedirectInfo]
Child attribute of type StateObjectIf a redirect variation was executed on the previous page, all the details of that experiment are accessible on the next page through the getRedirectInfo() function.
getVariationMap
function[getVariationMap]
Child attribute of type StateObjectGet a mapping from each experiment the visitor has ever seen to its current corresponding variation.
getDecisionString
function[getDecisionString]
Child attribute of type StateObjectGet a single string describing the campaign/experiment decision for a given campaign ID.
getDecisionObject
function[getDecisionObject]
Child attribute of type StateObjectGet an object with strings that describe the campaign / experiment decision for a given campaign ID.

Example Call

state = window["optimizely"].get("state");

Example Return Value

state.getActivationId();
state.getActiveExperimentIds();
state.getCampaignStates(filters);
state.getExperimentStates(filters);
state.getPageStates(filters);
state.getRedirectInfo();
state.getVariationMap();
state.getDecisionString();
state.getDecisionObject();

getCampaignStates()

Get all the campaigns and their current states.

Syntax

state.getCampaignStates(filter);

Parameters

Parameter and TypeChild AttributeDescription
filter
CampaignFilterObject or CampaignFilterFunction
N/AAn object with fields to filter on.
isActive
Boolean
Child attribute of
type CampaignFilterObject
Indicates if the campaign is active.

Return value

Parameter and TypeChild AttributeDescription
object[CampaignStateObject]N/AReturns an object. The object keys are campaign IDs. The values describe the state of every campaign.
id
string
Child attribute of type CampaignStateObjectThe ID of the campaign.
campaignName
string
Child attribute of type CampaignStateObjectThe name of the campaign.
experiment
NameIdObject
Child attribute of type CampaignStateObjectAn object with the name and the ID of the experiment the visitor is bucketed in.
id
string
Child attribute of experiment type NameIdObjectThe ID of the object.
name
string
Child attribute of experiment type NameIdObjectThe name of the object.
variation
NameIdObject
Child attribute of type CampaignStateObjectAn object with the name and the ID of the variation the visitor is bucketed in.
id
string
Child attribute of variation type NameIdObjectThe ID of the object.
name
string
Child attribute of variation type NameIdObjectThe name of the object.
isActive
string
Child attribute of type CampaignStateObjectIndicates if the campaign is currently active.
visitorRedirected
string
Child attribute of type CampaignStateObjectIndicates if the visitor was redirected due to this campaign.
isInCampaignHoldback
Boolean
Child attribute of type CampaignStateObjectIndicates if the visitor is in the campaign holdback.
audiences
array
Child attribute of type CampaignStateObjectAudiences the visitor was in at the moment the campaign activated.

Example Call

state.getCampaignStates({
  "isActive": true
});

Example Return Value

{
  "6676370413": {
    "id": "6676370413",
    "campaignName": "Example personalization campaign",
    "experiment": {
      "id": "6666781105",
      "name": null
    },
    "variation": {
      "id": "6626731852",
      "name": "Variation #1"
    },
    "isActive": true,
    "visitorRedirected": false,
    "isInCampaignHoldback": false,
    "audiences": [{
      "id": "6672770135",
      "name": "Chrome users"
    }]
  }
}

Description

Get all the campaigns and their current states. The filter argument allows you to filter the campaigns. It's possible to filter using an object or with a function.

Examples

Filter with a function

Filter the campaigns with a filter function.

Example code for Filter with a function

var state = window["optimizely"].get("state");

state.getCampaignStates(function(campaignState) {
  return !!campaignState.isActive;
});

getExperimentStates()

Get all the experiments and their current states.

Syntax

state.getExperimentStates(filter);

Parameters

Parameter and TypeChild AttributeDescription
filter
CampaignFilterObject or CampaignFilterFunction
N/AAn object with fields to filter on.
isActive
Boolean
Child attribute of
type CampaignFilterObject
Indicates if the experiment is active.

Return value

Parameter and TypeChild AttributeDescription
object[ExperimentStateObject]N/AReturns an object. The object keys are experiment IDs. The values describe the state of every experiment.
id
string
Child attribute of type ExperimentStateObjectThe ID of the experiment.
experimentName
string
Child attribute of type ExperimentStateObjectThe name of the experiment.
audiences
array[NameIdObject]
Child attribute of type ExperimentStateObjectAudiences the visitor was in when the experiment was activated.
id
string
Child attribute of audiences type NameIdObjectThe ID of the object. Required.
name
string
Child attribute of audiences type NameIdObjectThe name of the object. Required.
variation
NameIdObject
Child attribute of type ExperimentStateObjectAn object with the name and the ID of the variation the visitor is bucketed in, or null if the visitor was not bucketed.
id
string
Child attribute of variation type NameIdObjectThe ID of the object. Required.
name
string
Child attribute of variation type NameIdObjectThe name of the object. Required.
isActive
string
Child attribute of type ExperimentStateObjectIndicates if the experiment is currently active.
isInExperimentHoldback
Boolean
Child attribute of type ExperimentStateObjectIndicates if the visitor is in the holdback (i.e., is excluded due traffic allocation).
visitorRedirected
string
Child attribute of type ExperimentStateObjectIndicates if the visitor was redirected due to this experiment.

Example Call

state.getExperimentStates({
  "isActive": true
});

Example Return Value

{
  "6666781105": {
    "id": "6666781105",
    "experimentName": null,
    "variation": {
      "id": "6626731852",
      "name": "Variation #1"
    },
    "isActive": true,
    "visitorRedirected": false,
    "isInExperimentHoldback": false,
    "audiences": [{
      "id": "6672770135",
      "name": "Chrome users"
    }]
  }
}

Description

Get A/B experiments and their current states (excludes Personalization campaigns). The filter argument allows you to filter the experiments. It's possible to filter using an object or with a function.

Examples

Filter with a function

Filter the experiments with a filter function.

Example code for Filter with a function

var state = window["optimizely"].get("state");

// "Not variation #1"
state.getExperimentStates(function(expState) {
  return !expState.variation || expState.variation.name !== "Variation #1";
});

Filter with an object

Filter the experiments with a match object.

Example code for Filter with an object

var state = window["optimizely"].get("state");

state.getExperimentStates({
  isActive: true
});

getPageStates()

Get all the pages and their current states.

Syntax

state.getPageStates(filter);

Parameters

Parameter and TypeChild AttributeDescription
filter
PageFilterObject
N/AThe argument indicating to get data information.
isActive
boolean
Child attribute of type PageFilterObjectIndicates if the page is active.

Return value

Parameter and TypeChild AttributeDescription
object[PageStateObject]N/AReturns an object. The object keys are page IDs. The values describe the state of every page.
id
string
Child attribute of type PageStateObjectThe ID of the page.
name
string
Child attribute of type PageStateObjectThe name of the page.
apiName
string
Child attribute of type PageStateObjectThe apiName of the page.
staticConditions
array
Child attribute of type PageStateObjectThe category of the page.
category
string
Child attribute of type PageStateObjectThe URL conditions for this page object.
tags
array[TagObject]
Child attribute of type PageStateObjectThe tags associated to this page.
type
string
Child attribute of type TagObjectA static value that indicates that you are using the "tag" function. Required.
tags
PageTag
Child attribute of type TagObjectA single-level JSON object with metadata. This is equivalent to page tags but can be used when pages are already being activated using URL targeting.
*
*
Child attribute of type PageTagThis object can contain project- or environment-specific properties that are not predefined.
isActive
Boolean
Child attribute of type PageStateObjectIndicates if the page is currently active.

Example Call

state.getPageStates({
  "isActive": true
});

Example Return Value

{
  "6678290257": {
    "id": "6678290257",
    "name": "Homepage",
    "apiName": "homepage",
    "category": "other",
    "staticConditions": ["and", ["or", {
      "type": "url",
      "value": "https://developers.optimizely.com/",
      "match": "simple"
    }]],
    "tags": [{
      "category": "other",
      "locator": ".push-quad > a:nth-of-type(1)",
      "valueType": "string",
      "locatorType": "css_selector",
      "apiName": "view_docs_button"
    }],
    "isActive": true,
    "metadata": {
      "view_docs_button": "View Docs"
    }
  }
}

Description

Get all the pages and their current states. The filter argument allows you to filter the pages. It's possible to filter using an object or with a function.

Examples

Filter with a function

Filter the campaigns with a filter function.

Example code for Filter with a function

var state = window["optimizely"].get("state");

state.getCampaignStates(function(pageState) {
  return !!pageState.isActive;
});

getVariationMap()

Get a mapping from each experiment the visitor has ever seen to its current corresponding variation.

Syntax

state.getVariationMap();

Return value

Parameter and TypeChild AttributeDescription
object[VariationIdName]N/AAn object where the keys are the experiment IDs of every experiment the visitor has ever seen and the values are objects with the name, ID, and index of the variation a visitor saw for that experiment.
id
string
Child attribute of type VariationIdNameThe ID of the variation. Required.
name
string
Child attribute of type VariationIdNameThe name of the variation. Required.
index
number
Child attribute of type VariationIdNameThe index of the variation in its experiment's list of variations. The first item in the list has an index of 0. Required.

Example Call

state.getVariationMap();

Example Return Value

{
  "6661191859": {
    "id": "6670551924",
    "name": "Variation #1",
    "index": "1"
  }
}

Description

Get the mapping of all experiments the visitor has ever seen to its current corresponding variation. If the visitor is excluded from an experiment due to traffic allocation, that experiment will appear here
and they will be bucketed into a variation, but no visual changes will be applied.

getActiveExperimentIds()

Get an array of experiment IDs that are currently active on the page for the visitor.

Syntax

state.getActiveExperimentIds();

Return value

Parameter and TypeChild AttributeDescription
array[integer]N/AAn array of experiment IDs that are currently active on the page for the visitor.

Example Call

state.getActiveExperimentIds();

Example Return Value

["6661191859", "6666781105", "7555673865"]

Description

Get an array of experiment IDs that are currently active on the page for the visitor. If the visitor is excluded from an experiment due to traffic allocation, the experiment is considered active and they will be bucketed into a variation, but no visual changes will be applied. This situation is referred to as isInExperimentHoldback in the getExperimentStates API:

state.getExperimentStates()[{experiment_id}].isInExperimentHoldback

getRedirectInfo()

If a redirect variation was executed on the previous page, all the details of that experiment are accessible on the next page through the getRedirectInfo() function.

Syntax

state.getRedirectInfo();

Return value

Parameter and TypeChild AttributeDescription
null or RedirectInfoObjectN/AThe object contains all the details about a redirect experiment that ran on the previous page.
experimentId
string
Child attribute of type RedirectInfoObjectThe ID of the redirect experiment. Required.
variationId
string
Child attribute of type RedirectInfoObjectThe ID of the redirect variation. Required.
referrer
string
Child attribute of type RedirectInfoObjectThe value of the original referrer, before the redirect occurred. Required.

Example Call

state.getRedirectInfo();

Example Return Value

{
  "experimentId": "7669390999",
  "variationId": "7662661235",
  "referrer": "https://www.google.com/"
}

Description

If a redirect variation was executed on the previous page, all the details of that experiment are accessible on the next page through the getRedirectInfo() function. Most analytics integrations use this information to correct referrer values.

getDecisionString()

Get a single string describing the campaign/experiment decision for a given campaign ID.

Syntax

state.getDecisionString(config);

Parameters

Parameters and TypeChild AttributeDescription
config
DecisionConfigObject
N/AAn object with configuration fields for the function. Required.
campaignId
string
Child attribute of type DecisionConfigObjectIndicates the campaign to get the decision string for. Required.
shouldCleanString
Boolean
Child attribute of type DecisionConfigObjectIf true, any character that matches the regex /[^a-zA-Z0-9\.\~\!\*\(\)\']+/g is replaced with _. Default is false.
maxLength
number
Child attribute of type DecisionConfigObjectThe maximum length of the returned string. If the combined length of names and IDs is longer than the maxLength, the names will be individually truncated, with favor given to the campaign name. Default is 255 characters.

Return value

Parameter and TypeChild AttributeDescription
stringN/AFor personalization campaign decisions, the string returned is a concatenation of the decision campaign, experiment, and variation names and IDs, and holdback status. For A/B experiment decisions, the string returned is a concatenation of the decision experiment and variation names and IDs. More details on naming conventions for third-party integrations.

Example Call

state.getDecisionString({
  "campaignId": "6676370413"
});

Example Return Value

"Example personalization campaign(6676370413):Example experiment(6666781105):Variation #1(6626731852):holdback"

Description

Get a single string describing the campaign/experiment decision for a given campaign ID. This is often used to send campaign decision data to third-party analytics integrations. This function takes a campaign ID as a parameter; if the campaign in question is an AB test, make sure to still pass the campaign ID, and this API will return only the information that is relevant to an A/B test. This makes it so that code consuming this API does not have to conditionalize on whether the decision is for an AB test or a personalization campaign.

getDecisionObject()

Get an object with strings that describe the campaign/experiment decision for a given campaign ID.

Syntax

state.getDecisionObject(config);

Parameters

Parameter and TypeChild AttributeDescription
config
DecisionConfigObject
N/AAn object with configuration fields for the function. Required.
campaignId
string
Child attribute of type DecisionConfigObjectIndicates the campaign to get the decision string for. Required.
shouldCleanString
Boolean
Child attribute of type DecisionConfigObjectIf true, any character that matches the regex /[^a-zA-Z0-9\.\~\!\*\(\)\']+/g is replaced with _. Default is false.
maxLength
number
Child attribute of type DecisionConfigObjectThe maximum length of the returned string. If the combined length of names and IDs is longer than the maxLength, the names will be individually truncated, with favor given to the campaign name. Default is 255 characters.

Return value

Parameter and TypeChild attributeDescription
GetDecisionObjectReturnN/AFor personalization campaign decisions, the object returned contains values for the decision campaign, experiment, and variation names and IDs, and holdback status. For A/B experiment decisions, the object returned contains values for the decision experiment and variation names and IDs.
campaign
string or undefined
Child attribute of type GetDecisionObjectReturnA string representing the decision's campaign name and ID. Not included if campaign is an AB test.
experiment
string
Child attribute of type GetDecisionObjectReturnA string representing the decision's experiment name and ID.
variation
string
Child attribute of type GetDecisionObjectReturnA string representing the decision's variation name and ID.
holdback
Boolean or undefined
Child attribute of type GetDecisionObjectReturnWhether visitor was placed in the campaign holdback. Not included if campaign is an AB test.

Example Call

state.getDecisionObject({
  "campaignId": "6676370413"
});

Example Return Value

{
  "campaign": "Shopping Cart (6676370413)",
  "experiment": "New Visitors (3243212353)",
  "variation": "Variation #1 (2344343121)",
  "holdback": false
}

Description

Get an object with strings that describe the campaign/experiment decision for a given campaign ID. This is often used to send campaign decision data to third-party analytics integrations. This function takes a campaign ID as a parameter; if the campaign in question is an AB test, make sure to still pass the campaign ID, and this API will return only the information that is relevant to an A/B test. This makes it so that code consuming this API does not have to conditionalize on whether the decision is for an AB test or a personalization campaign.