Integrations Developer Guide

Welcome! This page walks you through everything you need to build an integration using Optimizely APIs.

Optimizely integrates with more than 30 Technology Partners including analytics solutions, data management platforms, content management systems, e-commerce platforms, conversion tracking solutions, and more. Many of these integrations are built entirely using public Optimizely APIs. On this page, you’ll find some common use cases for integrating with Optimizely and all the developer resources you need to build an integration.

Are you a prospective Technology Partner interested in building an integration with Optimizely? Please read the Technology Partners section to understand the required steps to get your integration built, approved, and launched by Optimizely.

Are you a current Optimizely customer interested in building a custom integration for your own use case? Jump straight to Integration Types to understand the different ways of integrating with Optimizely.

At any time, if you have questions about building integrations you can ask the developer community, or you can submit a ticket to the developer support team. We'll be happy to help.

Integration Types

Integrations with Optimizely typically fall into one of the following categories. For each category we've 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 X. It is an open framework built to deliver:

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’ve built any open source integrations, we encourage you to contribute them to our GitHub library. Email partner-enablement [at] optimizely [dot] com 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 3rd party demographic data such as gender, location, weather, and age, or 1st party behavioral data such as buying intent, lifetime value, cart abandonment, and more. 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

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. To avoid going over the limit with your account, create a free developer account. Creating a developer account does not require a credit card and will provide full access the REST API.

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 on 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 will 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 will now 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 (see here for documentation). The most straight-forward implementation is to create one custom attribute per imported audience and set the value to "true" for eligible visitors. Note that the conditions 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 would typically wrap this code in a conditional construct which 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 have verified the successful creation of 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 have created and qualify for the audience. Verify you are targeted by the experiment either by observing the variation change, or by enabling console logging.

If you are not targeted as expected, execute optimizely.get("visitor").custom in the developer console to see an array of custom attributes which have been set in your session. If your custom attribute does not 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

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. To avoid going over the limit with your account, create a free developer account. Creating a developer account does not require a credit card and will provide full access the REST API.

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.

This is an example of how it would work within 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 whether the snippet integration is working correctly, use the snippet integration form to add a snippet to a test page. If you have gone through all the steps of your form, the Optimizely snippet should be installed on the page. Verify whether 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 is installed on the page.

Technology Partners

If you would like to partner with Optimizely to help support your integration, we highly recommend you apply for the Technology Partner Program. Becoming a partner includes many benefits including hands-on developer support and marketing benefits to help promote your integration to Optimizely customers. For more information about requirements and benefits of the Technology Partner Program click here.

How to Become a Technology Partner

1. Create an Optimizely developer account

If you don't have an Optimizely developer account, just sign up for a free developer account. This account will give you access to the full set of Optimizely features and API access, but with limited traffic allocation. No credit card required.

2. Apply to Technology Partner Program

Please fill out the Technology Partner Program form to apply for the program. We recommend that you apply for the program before you start developing an integration so we can provide you with appropriate guidance using the Optimizely APIs and plan for launch.

3. Register your integration

We require all Technology Partners to formally register their integration to Optimizely so we can better track which APIs are most important to our partners. Registering your integration is easy. If your integration is using the REST API, we require you use OAuth 2.0 authentication and register your integration as an OAuth client . If your integration is using the JavaScript API, we also require you to make a one-line API call. The steps to register your integration are described in the Register your integration section.

4. Build your integration

There are many ways to integrate with Optimizely depending on your needs. To decide how to best integrate with our platform, please see the chart of Integration Types below which includes some common types of integrations built by customers and partners. Each integration type includes a step-by-step guide including example code that you can use to build the integration. If none of these integration types meet your needs, please refer to our REST API documentation.

5. Submit integration for QA

Our team is eager to provide feedback and make sure the integration works as expected. Please go through the Integration Checklist before submitting your integration to techpartners@optimizely.com to make the review process as quick and smooth as possible. You can find the checklist in the Integration Checklist section.

6. Promote your integration

After Optimizely has tested and approved your integration, you can work with your Partner Manager to get your integration listed in the Technology Partner Directory. As a Technology Partner you will also receive a Marketing Playbook that provides detailed guidance on the best way to promote your integration to Optimizely customers.

If you have any questions about becoming an Optimizely Technology Partner, please email techpartners@optimizely.com.

Integration Checklist

We will review Optimizely Integrations submitted to the techpartners@optimizely.com.

Follow this guide to help your integration go through the review process quickly and smoothly. We've highlighted the most important elements for your integration listing.

This guide does not replace or supersede our Developer Policy, which must be adhered to at all times. The Developer Policy is listed here: https://www.optimizely.com/terms-development/.

QA details

Sandbox account

Set up a working account that can be used by Optimizely employees to do functional testing.

Instructions

Provide high level testing instructions for an Optimizely employee to QA your integration. During the QA process, our engineers check the expected behavior. We aim to partner with great products, so we also expect to not encounter serious bugs in the product during QA.

Listing

Appropriate name

Your integration's name should not infringe upon a trademark or copyright for any other products or services. Also, if you have any reference to Optimizely in the Integration name, we will ask you to remove it. You can find our brand guides here: http://design.optimizely.com/. For an integration we recommend using your product name or a combination of your company name and your product name. Examples:

Logos

Optimizely needs two versions of your logo:

The following guidelines should be followed when creating an integration of application logo that will appear in Optimizely.

Designing the Logo:
Optimizely Logos
Logo for integrations dashboard
Logo for partner directory

This is how customers install your integration, so it's important to make it as easy as possible. It should contain:

As part of your submission to the Directory, you agree to "Keep your Integration updated and your support channel active" so please ensure that the link you provide is to an active and responsive support channel.

Customer support email

Please make sure this is an email address that you check regularly and is clearly connected to your app.

Registering your app

Make sure your integration activity is visible to Optimizely. Go through the steps described here:

https://developers.optimizely.com/integrations/#register-integration

Submit all information

Use all the information from above to fill in this form.

Registration

We require all partners that have an integration to register an OAuth 2.0 client. Using OAuth 2.0 provides the following benefits:

If your integration does not use the REST API, creating an OAuth 2.0 client is still a required step.

If you have questions about registering your integration, please email integrationsupport@optimizely.com.

The following step-by-step guide describes how register an OAuth 2.0 client.

1. Create an OAuth 2.0 client for your integration

Sign in to the account and navigate to https://app.optimizely.com/v2/accountsettings/registered-apps.

On this page, click on "Register New Application".

Fill in the fields with the following values:

Click Apply.

2. Implement API specific requirements

Integrations that use the REST API
We require every integration that uses the REST API to authenticate with the OAuth 2.0 client that you created in the previous step. Authentication with an OAuth 2.0 client is described in the REST API reference.

Integrations that use the JavaScript API
If your integration is using the JavaScript API, we also require you to make a one-line API call at the top of your integration's JavaScript:

window.optimizely = window.optimizely || [];
window.optimizely.push({
 'type': 'integration',
 'OAuthClientId': 5352110138 // This is the OAuth Client ID you've copied in the previous step.
});

The client ID used in the on-line API call can be found here: