State

53 min

Get the Optimizely state

Syntax

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

Parameters

Parameter and Type	Child attribute	Description
state (string)	N/A	The argument indicating to get the state object. Required.

Return value

Parameter and Type	Child attribute	Description
StateObject	N/A	An object with functions that return information about the current state of Optimizely Web Experimentation.
getActiveExperimentIds (function)	Child attribute of StateObject.	Get an array of experiment IDs that are currently active on the page for the visitor.
getCampaignStates (function)	Child attribute of StateObject.	Get all the campaigns and their current states.
getExperimentStates (function)	Child attribute of StateObject.	Get all the experiments and their current states.
getPageStates (function)	Child attribute of StateObject.	Get all the pages and their current states.
getRedirectInfo (function)	Child attribute of StateObject.	If a redirect variation executed on the previous page, return details of that experiment.
getVariationMap (function)	Child attribute of StateObject.	Get a mapping from each experiment the visitor has ever seen to its current corresponding variation.
getDecisionString (function)	Child attribute of StateObject.	Get a single string describing the decision for a given campaign ID.
getDecisionObject (function)	Child attribute of StateObject.	Get an object with strings that describe the decision for a given campaign ID.

Example

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

getCampaignStates()

Get all the campaigns and their current states. Use a filter object or function to limit the results.

Syntax

state.getCampaignStates(filter);

Parameters

Parameter and Type	Child attribute	Description
filter (CampaignFilterObject	CampaignFilterFunction)	Optional filter to limit results.

CampaignFilterObject fields

Parameter and Type	Child attribute	Description
isActive (boolean)	Child attribute of CampaignFilterObject.	Indicates if the campaign is active.

Return value

Parameter and Type	Child attribute	Description
object	N/A	Keys are campaign IDs. Values describe each campaign's state.
id (string)	Child attribute of CampaignStateObject.	Campaign ID.
campaignName (string)	Child attribute of CampaignStateObject.	Campaign name.
experiment (NameIdObject)	Child attribute of CampaignStateObject.	The experiment the visitor is bucketed in.
id (string)	Child attribute of experiment NameIdObject.	Object ID.
name (string)	Child attribute of experiment NameIdObject.	Object name.
variation (NameIdObject)	Child attribute of CampaignStateObject.	The variation the visitor is bucketed in.
id (string)	Child attribute of variation NameIdObject.	Object ID.
name (string)	Child attribute of variation NameIdObject.	Object name.
isActive (boolean)	Child attribute of CampaignStateObject.	Whether the campaign is currently active.
visitorRedirected (boolean)	Child attribute of CampaignStateObject.	Whether the visitor was redirected due to this campaign.
isInCampaignHoldback (boolean)	Child attribute of CampaignStateObject.	Whether the visitor is in the campaign holdback.
audiences (array)	Child attribute of CampaignStateObject.	Audiences the visitor was in when 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" }]
  }
}

Example: filter with a function

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

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

getExperimentStates()

Get A/B experiments and their current states (excludes Personalization campaigns). Use a filter object or function to limit results

Syntax

state.getExperimentStates(filter);

Parameters

Parameter and Type	Child attribute	Description
filter (CampaignFilterObject	CampaignFilterFunction)	N/A	Optional filter to limit results.

CampaignFilterObject fields

Parameter and Type	Child attribute	Description
isActive (boolean)	Child attribute of CampaignFilterObject.	Indicates if the experiment is active.

Return value

Parameter and Type	Child attribute	Description
object	N/A	Keys are experiment IDs. Values describe each experiments state.
id (string)	Child attribute of ExperimentStateObject.	Experiment ID.
experimentName (string)	Child attribute of ExperimentStateObject.	Experiment name.
audiences (array)	Child attribute of ExperimentStateObject.	Audiences the visitor was in when the experiment was activated.
id (string)	Child attribute of audiences NameIdObject.	Object ID. Required.
name (string)	Child attribute of audiences NameIdObject.	Object name. Required.
variation (NameIdObject	Child attribute of ExperimentStateObject or null.	Variation bucketed into, or null if not bucketed.
id (string)	Child attribute of variation NameIdObject.	Object ID. Required.
name (string)	Child attribute of variation NameIdObject.	Object name. Required.
isActive (boolean)	Child attribute of ExperimentStateObject.	Whether the experiment is currently active.
isInExperimentHoldback (boolean)	Child attribute of ExperimentStateObject.	Whether the visitor is excluded due to traffic allocation.
visitorRedirected (boolean)	Child attribute of ExperimentStateObject.	Whether 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" }]
  }
}

Examples

Filter with a function

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

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

Filter with an object

const 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 Type	Child attribute	Description
filter (PageFilterObject)	N/A	Optional filter to limit results.
isActive (boolean)	Child attribute of PageFilterObject.	Indicates if the page is active.

Return value

Parameter and Type	Child attribute	Description
object	N/A	Keys are page IDs. Values describe each page's state.
id (string)	Child attribute of PageStateObject.	Page ID.
name (string)	Child attribute of PageStateObject.	Page name.
apiName (string)	Child attribute of PageStateObject.	API name of the page.
staticConditions (array)	Child attribute of PageStateObject.	URL conditions for the page object.
category (string)	Child attribute of PageStateObject.	Page category.
tags (array)	Child attribute of PageStateObject.	Tags associated with the page.
type (string)	Child attribute of TagObject.	Static value indicating the tag function (required).
tags (PageTag)	Child attribute of TagObject.	Single-level JSON object with metadata (for URL-targeted pages).
* (*)	Child attribute of PageTag.	Arbitrary project- or environment-specific properties.
isActive (boolean)	Child attribute of PageStateObject.	Whether 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" }
  }
}

Example: filter with a function

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

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

Note The previous example demonstrates function-style filtering. Swap in getPageStates if you prefer to filter page states specifically.

getVariationMap()

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, the experiment is considered active and the visitor is bucketed into a variation, but no visual changes are applied.

Syntax

state.getVariationMap();

Return value

Parameter and Type	Child attribute	Description
object	N/A	Keys are experiment IDs; values are variation descriptors.
id (string)	Child attribute of VariationIdName.	Variation ID. Required.
name (string)	Child attribute of VariationIdName.	Variation name. Required.
index (number)	Child attribute of VariationIdName.	Index of the variation in the experiment’s list (0-based). Required.

Example call

state.getVariationMap();

Example return value

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

getActiveExperimentIds()

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 the visitor is bucketed into a variation, but no visual changes are applied. This situation is referred to as isInExperimentHoldback in the getExperimentStates API.

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

Syntax

state.getActiveExperimentIds();

Return value

Parameter and Type	Child attribute	Description
array<string>	N/A	An array of experiment IDs that are currently active on the page for the visitor.

Example call

state.getActiveExperimentIds();

Example return value

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

getRedirectInfo()

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

Use this when you need to correct referrer values in analytics after a redirect variation.

Syntax

state.getRedirectInfo();

Return value

Parameter and Type	Child attribute	Description
null	RedirectInfoObject	Details about a redirect experiment that ran on the previous page, or null if none.
experimentId (string)	Child attribute of RedirectInfoObject.	Redirect experiment ID. Required.
variationId (string)	Child attribute of RedirectInfoObject.	Redirect variation ID. Required.
referrer (string)	Child attribute of RedirectInfoObject.	Original referrer value before the redirect. Required.

Example call

state.getRedirectInfo();

Example return value

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

getDecisionString()

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

Often used to send campaign decision data to third-party analytics. Pass a campaign ID. If the campaign is an A/B test, the API returns only the fields relevant to A/B tests. Your code does not need to branch on campaign type.

Syntax

state.getDecisionString(config);

Parameters

Parameters and Type	Child attribute	Description
config (DecisionConfigObject)	N/A	Configuration for the function. Required.
campaignId (string)	Child attribute of DecisionConfigObject.	Campaign ID to get the decision string for. Required.
shouldCleanString (boolean)	Child attribute of DecisionConfigObject.	If true, replace characters matching /[^a-zA-Z0-9\.\~\!\*\(\)\']+/g with _. Default: false.
maxLength (number)	Child attribute of DecisionConfigObject.	Maximum length of the returned string. Names are truncated preferentially (campaign first) to meet the limit. Default: 255.

Return value

Parameter and Type	Child attribute	Description
string	N/A	For personalization decisions: concatenation of campaign, experiment, and variation names or IDs and holdback status. For A/B decisions: concatenation of experiment and variation names or IDs.

Example call

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

Example return value

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

getDecisionObject()

Get an object with strings that describe the campaign or experiment decision for a given campaign ID. Often used to send campaign decision data to third-party analytics. Pass a campaign ID. If the campaign is an A/B test, the API returns only A/B-relevant fields so your code does not need to branch on type.

Syntax

state.getDecisionObject(config);

Parameters

Parameter and Type	Child attribute	Description
config (DecisionConfigObject)	N/A	Configuration for the function. Required.
campaignId (string)	Child attribute of DecisionConfigObject.	Campaign ID to get the decision object for. Required.
shouldCleanString (boolean)	Child attribute of DecisionConfigObject.	If true, replace characters matching /[^a-zA-Z0-9\.\~\!\*\(\)\']+/g with _. Default: false.
maxLength (number)	Child attribute of DecisionConfigObject.	Maximum length of returned string fields. Default: 255.

Return value

Parameter and Type	Child attribute	Description
GetDecisionObjectReturn	N/A	For personalization decisions, contains fields for campaign, experiment, variation, and holdback status. For A/B decisions, contains fields for experiment and variation.
campaign (string	Child attribute of GetDecisionObjectReturnor undefined.	Decision's campaign name and ID. Not included for A/B tests.
experiment (string)	Child attribute of GetDecisionObjectReturn.	Decision’s experiment name and ID.
variation (string)	Child attribute of GetDecisionObjectReturn.	Decision's variation name and ID.
holdback (boolean	Child attribute of GetDecisionObjectReturn or undefined.	Whether the visitor was placed in the campaign holdback. Not included for A/B tests.

Example call

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

Example return value

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