HomeGuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityLog In

Integration types

This topic describes the various categories of Optimizely Integrations.

Integrations with Optimizely typically fall into one of the following categories. For each category we have included some examples as well as a link to an implementation guide with step-by-step instructions on how to build the integration.

Analytics

Optimizely offers a custom analytics integration solution to enable users to build their own analytics integrations on top of Optimizely. It is an open framework built to deliver:

  • Flexibility in timing and data sent to third-party analytics tools.
  • Improved data consistency between Optimizely and third-party analytics tools.
  • The opportunity to reduce the number of events sent to third-party analytics tools, which can reduce costs for analytics tools that charge per event.
  • A standardized process for experiment setup, reducing the number of mistakes from selecting incorrect custom dimensions or values.

You can read our in-depth knowledge base article to learn more about how to create your own analytics integrations using custom code, and example integrations can be found in our GitHub library. There is also a troubleshooting article that can be helpful when building an integration.

If you have built any open-source integrations, we encourage you to contribute them to our GitHub library. Email [email protected] to begin the process of submitting a contribution.

Audiences

Audience Integrations allow customers to target a specific audience based on data from an external source. With a simple drag-and-drop interface, customers can personalize content and experiments based on third-party demographic data such as gender, location, weather, and age, or first-party behavioral data such as buying intent, lifetime value, and cart abandonment. This section explains how to create audiences within Optimizely (via the REST API) and add a visitor to that audience in the browser (via the JavaScript API).

Prerequisites

  • Audience data from your platform is available client-side (i.e., in the browser).
  • You're comfortable using REST APIs.
  • You possess basic JavaScript skills

1. Log in to your Optimizely account

Log in to the Optimizely Application.

2. Register your application

We require you to use OAuth 2.0 to authenticate with the Optimizely REST API. This will allow you to provide a seamless experience to users in your application who want to install the Optimizely snippet. Learn how to connect to Optimizely using OAuth 2.0.

3. Create a test page

Create a page to test the integration on. On the test page, the Optimizely snippet needs to be added to the top of the <head> section. Instructions on how to install the Optimizely snippet can be found in our Knowledge Base.

4. Create a custom attribute

You can now create custom attributes via the REST API. Custom attributes are set via the JavaScript API and can be used to define audience conditions. When a user indicates that they want to use an audience from your platform within Optimizely, you should create a custom attribute to store information about that audience. You'll use this attribute when creating an Optimizely audience in the next step. Learn how to create custom attributes in Optimizely using the REST API.

An example of the Optimizely REST API call with cURL is displayed here:

curl -X POST \
  -H "Authorization: Bearer abcdefg123456" \
  -H "Content-Type: application/json" -d @- \
  "https://api.optimizely.com/v2/attributes"
{
  "key": "my_integration_attribute",
  "archived": false,
  "project_id": 12345678,
  "name": "My Integration Attribute"
}

Note the key of the newly created custom attribute, as you will use it when defining an audience and setting values for the attribute via the JavaScript API.

5. Create an Optimizely audience

You'll next use your custom attribute to define an Optimizely audience using the REST API. Audiences are constructed using one or more conditions, where conditions are an expression that can be evaluated as True or False. Conditions are expressed as JSON objects. The most straightforward implementation is to create one custom attribute per imported audience and set the value to "true" for eligible visitors. Note that the condition's object references the key defined during attribute creation as name. Learn how to create audiences in Optimizely using the REST API.

An example of the Optimizely REST API call with cURL is displayed here:

curl -X POST \
  -H "Authorization: Bearer abcdefg123456" \
  -H "Content-Type: application/json" -d @- \
  "https://api.optimizely.com/v2/audiences"
{
  "project_id": 12345678,
  "archived": false,
  "conditions": "[\"and\", {\"type\": \"custom_attribute\", \"name\": \"my_integration_attribute\", \"value\": \"true\"}]",
  "description": "Visitor belongs to externally defined audience",
  "is_classic": false,
  "name": "My Integration Audience",
  "segmentation": false
}

6. Set custom attribute values

The Optimizely JavaScript API allows you to programmatically set values for custom attributes for a visitor. Your integration should deploy this code above the Optimizely snippet or via Optimizely's project JavaScript (which is possible to update via the REST API). You'd typically wrap this code in a conditional construct that checks the client-side representation of your product's audiences to determine if a visitor qualifies for a given audience. To set a custom attribute value, you can use the following function:

window["optimizely"].push({
  "type": "user",
  "attributes": {
    "my_integration_attribute": "true"
  }
});

Note that keys in the attributes dictionary correspond with the key used when creating custom attributes in Step 4 of this process.

7. QA your integration

To verify that the integration works, select an audience within your platform that you can qualify for. Trigger the procedure to create a corresponding Optimizely custom attribute and audience.

Verify that the custom attribute creation has worked by going to https://app.optimizely.com/v2/projects/{{ project_id }}/audiences/attributes. The newly created custom attribute should appear in the list.

Verify that the audience creation has worked by going to https://app.optimizely.com/v2/projects/{{ project_id }}/audiences. The newly created audience should appear in the list. You can edit the audience to confirm that it uses the correct custom attribute as a condition.

Once you've verified the successful creation of a custom attribute and audience, create and start an experiment that uses the audience. Go to your Experiments dashboard and create a new experiment. As part of the experiment setup, select your newly created audience. Build a simple variation and start the experiment.

Go to the test page you created and qualify for the audience. Verify you're targeted by the experiment either by observing the variation change or by enabling console logging.

If you're not targeted as expected, execute optimizely.get("visitor").custom in the developer console to see an array of custom attributes that have been set in your session. If your custom attribute doesn't appear as expected, check the JavaScript your integration uses to set custom attribute values (described in Step 6).

Snippet installation

Snippet integrations allow users to implement the Optimizely functionality on their website without the help of a developer to add the Optimizely snippet.

Prerequisites

Your platform is able to programmatically modify HTML templates.

1. Create a developer account

Depending on your Optimizely plan type, the REST API may restrict the number of calls you can make per month.

2. Register your application

We require you to use OAuth 2.0 to authenticate with the Optimizely REST API. This will allow you to provide a seamless experience to users in your application who want to install the Optimizely snippet. Learn how to connect to Optimizely using OAuth 2.0.

3. Create a configuration form

Within your platform, you should add a form for installing Optimizely in a place only Administrators have access to. The configuration form should consist of a button to authenticate with Optimizely using OAuth and a selector for selecting the project that the user wants to install on their website. This is an example form:

After connecting with Optimizely, you can use the REST API to get all the projects connected to the account that the user authenticated with. To get all the project names and their corresponding project IDs, use the list-projects REST API call.

4. Implement snippet in the head section of every page

Write custom code that automatically adds the Optimizely snippet to every page using the project ID that was chosen by the user.

Here's an example of how that code would be configured in WordPress:

/**
 * Generates the Optimizely script tag.
 * @param int $project_code
 * @return string
 */
function optimizely_generate_script( $project_id ) {
  return '<script src="//cdn.optimizely.com/js/' . abs( floatval( $project_id ) ) . '.js"></script>';
}

/**
 * Force Optimizely to load first in the head tag.
 */
function optimizely_add_script() {
  $project_id = get_option( 'optimizely_project_id' );
  if ( ! empty( $project_id ) ) {
    // This cannot be escaped since optimizely_generate_script returns a script tag.
    // The output of this script is fully escaped within the function below
    echo optimizely_generate_script( $project_id );
  }
}
add_action( 'wp_head', 'optimizely_add_script', -1000 );

Want to learn more about the wp_head function used above? Check out the WordPress documentation here.

5. QA your integration

To verify that the snippet integration is working correctly, use the snippet integration form to add a snippet to a test page. If you've gone through all the steps of your form, the Optimizely snippet should be installed on the page. Verify that the snippet integration is working correctly by going to the test page on the website and opening the JavaScript console. When you execute window["optimizely"].get('data').projectId, Optimizely should return the project ID that's installed on the page.


Did this page help you?