Overview

The Optimizely client API provides a way for developers to modify the normal behavior of the Optimizely snippet for specific use cases. Use the API to target activation based on specific page content or events, query the state of activation, bucketing, or conversion for use in custom analytics packages, and force visitors into specific variations, among other capabilities.

The Optimizely client API has two parts:

API Function Calls

The Optimizely API function calls are used to direct Optimizely to take specific actions.

One example is starting experiments manually rather than upon page load, which is useful for testing dynamic web pages. Your application can tell Optimizely when to activate these "manual activation mode" experiments with the activate API function. Another example is using the bucketVisitor API function to assign visitors to a specific variation if you wanted to incorporate inputs that Optimizely's traffic allocation algorithm does not. The API function calls expose many of Optimizely's decisions and actions so you can take control.

Data Object

Optimizely's Data Object is a read-only data object that contains information about a visitor and his or her Optimizely experiments, variations, and goals. Use the Data Object to retrieve the state of and details about Optimizely experiments, variations, and goals for a given visitor. An example of this is retrieving which experiments and variations a visitor has seen and passing this information to your internal database.

Tutorials

See the Tutorials page for more examples of solutions using the Optimizely API.

API Function Calls

Before ever making an Optimizely function call you should use the following asynchronous instantiation line. The purpose of this line is to ensure that the Optimizely code has already been loaded or, if it has not been loaded, to queue the function calls in a JavaScript array. This is similar to Google Analytics' asynchronous function calls. The following is the code you should use:

window['optimizely'] = window['optimizely'] || [];

Optimizely function calls can be made using JavaScript or a query parameter, optimizely_function_name=value. The JavaScript API is used when the function should be called as part of your application, such as when activating a manual activation mode experiment. The query parameters are used most often for testing and debugging purposes. A common example is to opt a visitor out of Optimizely tracking by loading the URL with the query parameter optimizely_opt_out=true. The URL might look like this:

http://www.example.com/page.html?optimizely_opt_out=true

Activate

Activate manual activation mode experiments. When you call "activate" the given experiment is run if the visitor meets the experiment's targeting conditions.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["activate", experimentId]);

Activate SiteCatalyst

Integrate with SiteCatalyst. You must call "activateSiteCatalyst" after the "s_code.js" file has loaded.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["activateSiteCatalyst", {"sVariable": mySVar}]);

The sVariable parameter is optional. By default, Optimizely will use the variable "s" as the SiteCatalyst variable. For more information, see:
https://help.optimizely.com/hc/en-us/articles/200039985

Bucket Visitor

Assign a visitor to a specific variation, thus overriding Optimizely's random assignment mechanism. You must call "bucketVisitor" prior to loading the Optimizely snippet. It's also important to note that bucketing a visitor via the API will add the user as a visitor to the experiment regardless of whether or not they match any of the targeting conditions for the experiment. The experimentId and variationIds can be found in an experiment's Diagnostic Report.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["bucketVisitor", experimentId, variationId]);
<script src="//cdn.optimizely.com/js/xxxxxxxx.js">

Other ways to call this API:

// Multivariate experiments should bucket for each section:
window['optimizely'].push(["bucketVisitor", experimentId, variationIdOfSection1]);
window['optimizely'].push(["bucketVisitor", experimentId, variationIdOfSection2]);
// You can also use the variation index:
window['optimizely'].push(["bucketVisitor", experimentId, variationIndex]);

The variationIndex is a 0-based index of the variation in the editor (0 being the original page, 1 being the first variation, and so on).

Custom Tag

You can use custom tags to target based on information you have about a visitor. You must call "customTag" prior to loading the Optimizely snippet.

<script>
window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["customTag", tagKey, tagValue]);
</script>
<script src="//cdn.optimizely.com/js/xxxxxxxx.js">

You can also set multiple tags simultaneously:

window['optimizely'].push(["customTag", {
      firstKey: firstValue,
      secondKey: secondValue
}]);

If you set multiple values for the same tag key, the last value set before the Optimizely snippet loads will be used. You can check what values are actually set by checking the custom tags field on the data object after the Optimizely snippet loads.

Note that for targeting purposes, values are all compared as strings.

Delay Pageview Tracking

Delay pageview tracking by a specified number of milliseconds.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["delayPageviewTracking", 1000]);

Disable

Disable Optimizely entirely. You must call "disable" prior to loading the Optimizely snippet.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["disable"]);

You can also disable just Optimizely tracking calls from being made:

window['optimizely'].push(["disable", "tracking"]);

Log

Tell Optimizely to output its log to the browser's console log.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["log"]);

You can also do this by using the query parameter optimizely_log=true.

Visitor Opt Out

Opt a visitor out of Optimizely tracking. For example, you may want to opt visitors out of Optimizely tracking as part of your site's broader opt-out preferences.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["optOut"]);

You can also do this by using the query parameter optimizely_opt_out=true.

3rd Party Cookie Opt Out

Disable Optimizely's 3rd party cookies. You must call "optOutThirdPartyCookies" prior to loading the Optimizely snippet. This will prevent cross-domain visitor bucketing and measurement. For more information on Optimizely's use of cookies, please see our Knowledge Base.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["optOutThirdPartyCookies"]);

Set Cookie Expiration

Specify the number of days before the Optimizely visitor cookies will be set to expire. You must call "setCookieExpiration" prior to loading the Optimizely snippet. The minimum number of days that can be set is 90 (approximately 3 months). For more information on how Optimizely uses cookies, visit our Learning Center.

Note: Some Optimizely cookies are re-set every time a visitor comes to the site, which means the expiration period set with this API call will be used each time the cookie is set.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["setCookieExpiration", 365])

In the example above, the Optimizely visitor cookies will expire in 1 year.

Set Cookie Domain

Instruct Optimizely to set its cookies on a specific subdomain instead of the default domain. You must call "setCookieDomain" prior to loading the Optimizely snippet. By default, Optimizely sets its cookies on the domain, in order to work across subdomains.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["setCookieDomain", "www.example.com"])

In this example, the cookies Optimizely sets will be available only on ".www.example.com", ("www.example.com" and all of its subdomains), rather than on ".example.com", which is the default.

Track Element

Track clicks on elements matching "selector" with the event "eventName". You can call bindTrackElement before or after the Optimizely JavaScript snippet:

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["bindTrackElement", "selector",
                           "eventName"]);

or from within variation code or global JavaScript:

optimizely.push(["bindTrackElement", "selector", "eventName"]);

Track Event

Basic Tracking

Track custom events in Optimizely. The event "eventName" will be tracked and associated with the current visitor.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["trackEvent", "eventName"]);

Umsatzverfolgung

Track revenue-generating events. The event "eventName" will be tracked and associated with a revenue of valueInCents.

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(["trackEvent", "eventName", {"revenue": valueInCents}]);

valueInCents should be an integer equal to 100 times the value in dollars (or another currency if you prefer). For example, if you wish to track a purchase of $23.95, you would call:

window['optimizely'].push(["trackEvent", "purchase", {"revenue": 2395}])

Besuchersegmente

Accounts with segmentation enabled can add visitors to visitor segments through the API. To do so, first navigate to the dashboard page. Then find your visitor segment's api identifier by clicking through the information in the visitor segment dialog. The segment api identifier is automatically generated when you first create the visitor segment, but can be changed later.

To add a visitor to a segment, use:

window['optimizely'] = window['optimizely'] || [];

window['optimizely'].push(['addToSegment', 'apiIdentifier',
                           'optionalSegmentValue']);

To remove a visitor from a segment, use:

window['optimizely'].push(['removeFromSegment', 'apiIdentifier']);

To remove a visitor from all segments, use:

window['optimizely'].push(['removeFromAllSegments']);

The Data Object

The window['optimizely'].data object contains read-only information about the current user and the running experiments.

Custom Tags

window['optimizely'].data.customTags

window['optimizely'].data.customTags is an object that contains all the key-value pairs you've sent to Optimizely using the custom tag function.

Experimente

The Experiments Object

window['optimizely'].data.experiments

window['optimizely'].data.experiments is an object with information about all the experiments for this project file. The keys of window['optimizely'].data.experiment are the experiment ids, which can be found in the diagnostic report for your experiment.

Experiment Code

window['optimizely'].data.experiments[experimentId].code

window['optimizely'].data.experiments[experimentId].code contains the experiment's global JavaScript code, if any.

Experiment Manual Mode

window['optimizely'].data.experiments[experimentId].manual

window['optimizely'].data.experiments[experimentId].manual is a boolean indicating whether the experiment is a manual experiment or not.

Name des Experiments

window['optimizely'].data.experiments[experimentId].name

window['optimizely'].data.experiments[experimentId].name is the experiment's name.

Experiment Section Ids

window['optimizely'].data.experiments[experimentId].section_ids

window['optimizely'].data.experiments[experimentId].section_ids contains the section ids for the experiment, if it is a multivariate experiment.

Experiment Variation Ids

window['optimizely'].data.experiments[experimentId].variation_ids

window['optimizely'].data.experiments[experimentId].variation_ids is an array of variation ids for the variations of this experiment.

Bereiche

The Sections Object

window['optimizely'].data.sections

The window['optimizely'].data.sections object contains information about all the project file's sections, indexed by their section id. The section ids can be found in the diagnostic report. Only multivariate experiments contain sections.

Section Name

window['optimizely'].data.sections[variationId].name

window['optimizely'].data.sections[variationId].name contains the section's name.

Section Variation Ids

window['optimizely'].data.sections[variationId].variation_ids

window['optimizely'].data.sections[variationId].variation_ids is an array containing the variation ids for this section.

State

The State Object

The window['optimizely'].data.state object contains information about the current state of Optimizely, such as the active variations and the visitor's bucket map.

Aktive Experimente

window['optimizely'].data.state.activeExperiments

window['optimizely'].data.state.activeExperiments is an array of experiment ids for all the active experiments.

Variation Map

window['optimizely'].data.state.variationMap

window['optimizely'].data.state.variationMap is a hash table whose keys are the experiment ids of experiments running for the visitor (including inactive experiments for which the user has been bucketed), and whose values are the variation indexes for those experiments.

Variation Ids Map

window['optimizely'].data.state.variationIdsMap

window['optimizely'].data.state.variationIdsMap is a hash table whose keys are the experiment ids of experiments running for the visitor (including inactive experiments for which the user has been bucketed), and whose values are the variation ids for those experiments.

Variation Names Map

window['optimizely'].data.state.variationNamesMap

window['optimizely'].data.state.variationNamesMap is a hash table whose keys are the experiment ids of experiments running for the visitor (including inactive experiments for which the user has been bucketed), and whose values are the variation names for those experiments.

Variations

The Variation Object

window['optimizely'].data.variations

window['optimizely'].data.variations is an object with information about all the project file's variations, indexed by their variation id. The variation ids can be found in the diagnostic report.

Variation Name

window['optimizely'].data.variations[variationId].name

window['optimizely'].data.variations[variationId].name contains the variation's name.

Variation Map

window['optimizely'].data.variations[variationId].code

window['optimizely'].data.variations[variationId].code contains the variation's JavaScript code..

Visitor

The Visitor Object

window['optimizely'].data.visitor

window['optimizely'].data.visitor contains helpful information about the visitor to Optimizely.

Visitor Browser

window['optimizely'].data.visitor.browser

window['optimizely'].data.visitor.browser is a string containing information about the browser type that the visitor is using. Options include "Firefox", "Google Chrome", "Internet Explorer", "Opera", and "Safari". If Optimizely does not recognize the browser, this will be an empty string.

Visitor Location

window['optimizely'].data.visitor.location
window['optimizely'].data.visitor.location.city
window['optimizely'].data.visitor.location.region
window['optimizely'].data.visitor.location.country

For Platinum customers only, window['optimizely'].data.visitor.location is an object containing information about the visitor's location. Specifically, window['optimizely'].data.visitor.location.city, window['optimizely'].data.visitor.location.region, and window['optimizely'].data.visitor.location.country contain the names of the visitor's city, region, and country, if detected.

Region can also be a territory, such as Canadian province, Indian state, or German state. For US states and Canadian provinces, the string will be the standard two-letter abbreviation of the state, e.g. "NH" for New Hampshire, "DC" for the District of Columbia, and "ON" for Ontario. In some cases, the region string could refer to different places. For example, "MN" could be Minnesota, the US state, or Manipur, the Indian state. The region information should be used in conjunction with the country information, in order to be sure the region is for the correct country.

The country value is a two-letter abbreviation of the visitor's country, if one is detected. For example, "US" is the United States, "CA" is Canada, "MX" is Mexico, "DE" is Germany, "JP" is Japan, "GB" is Great Britain, and "RU" is Russia.

Visitor Referrer

window['optimizely'].data.visitor.referrer

window['optimizely'].data.visitor.referrer is a string listing the visitor's referring URL, if any. This is functionally equivalent to document.referer.

Visitor OS

window['optimizely'].data.visitor.os

window['optimizely'].data.visitor.os is a string listing the visitor's operating system. If the operating system is unknown, this string is the empty string.