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.

If you have questions about building integrations, you can ask the developer community, or you can submit a ticket to the developer support team at any time. We'll be happy to help as you build your integration.

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.

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 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.

Category Examples Description
Analytics Adobe Analytics
Google Analytics
Mixpanel
Analytics integrations allow customers to track Optimizely experiments in an external analytics tool. With the flip of a switch, Optimizely can append experiment data to analytics tracking code, so customers can see the impact of their experiments in their analytics tool. Implementation Guide
Audiences BlueKai
Demandbase
Tealium
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. Implementation Guide
Uploaded Lists Uploaded List integrations allow customers to upload a list of user identifiers (e.g. cookies, query parameters, or other user identifiers) to Optimizely from a 3rd party application, which can be used to target experiments and segment results. Unlike audience integrations which operate client-side, user list integrations are implemented by a server-to-server exchange. Implementation Guide
Content Management WordPress
Parse.ly
Content Management integrations allow customers to utilize the full power of Optimizely directly from a platform that manages content. Customers can create, configure, and run experiments directly from their content platform interface without having to login to Optimizely. Implementation Guide
Conversion Tracking DialogTech
FreeSpee
AVANSER
Conversion Tracking integrations allow customers to use custom events (e.g. phone calls) as a goal for their experiments, as opposed to default goals (eg. clicks or pageviews). These integrations use Optimizely’s custom event goals functionality to track conversions. Implementation Guide
Snippet Installation Demandware
EPiServer
Snippet integrations allow users to implement the Optimizely functionality on their website without the help of a developer to add the Optimizely snippet. Implementation Guide


Not seeing the platform you’re looking for? Check out the full list of platforms that Optimizely integrates with.

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 behaviour. 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 guidelines 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/accountsettings/apps/developers.

On this page, click on "Register a 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:

Analytics

Analytics integrations allow customers to track Optimizely experiments in an external analytics tool. With the flip of a switch, Optimizely can append experiment data to analytics tracking code, so customers can see the impact of their experiments in their analytics tool. The following step-by-step guide describes how to implement an analytics integration.

Prerequisites

1. Add the snippet

To get started, install the Optimizely snippet on your test page. This is the page you’ll test your integration on. The snippet should be added as high up in the <head> tag as possible. To learn how to install the Optimizely snippet, check out this step-by-step guide in our knowledge base.

2. Create and start an experiment

Create an experiment within your Optimizely account that runs on the test page you have created in Step 1. Save your experiment without making any changes. Click Start Experiment.

To verify that your experiment is running, do a hard refresh on the test page outside of the Editor. Open the JavaScript console and execute optimizely.activeExperiments. When your experiment is live, the console will output an array with your Experiment ID. It may take up to 2 minutes for the experiment to fully upload to your test page. If you don’t see the Experiment ID appear, wait for a few seconds, then execute the call again.

3. Write the integration code

To integrate with the analytics platform, you’ll need the Optimizely Experiment and Variation names that are running on the test page. This section describes the JavaScript methods you’ll need to retrieve this information:

Implement these methods below the Optimizely snippet on your test page. By combining the methods, you will be able to access all the experiment names and variation names. You can read more about the above methods in the JavaScript API reference.

<script>
if (window['optimizely'] && window['optimizely']['data']) {
  var activeExperiments = window['optimizely'].data.state.activeExperiments;
  if(window['optimizely'].data.state.redirectExperiment) {
    var redirectExperimentId = window['optimizely'].data.state.redirectExperiment.experimentId;
    var index = window['optimizely'].data.state.activeExperiments.indexOf(redirectExperimentId);
    if(index === -1){
      activeExperiments.push(redirectExperimentId);
    }
    // Some analytics platforms have the ability to fix referrer values. Use optimizely.data.state.redirectExperiment.referrer to fix the referrer value here.

  }

  for (var i = 0; i < activeExperiments.length; i++) {
    var experimentId = activeExperiments[i];
    var variationName = window['optimizely'].data.state.variationNamesMap[experimentId];
    var experimentName = window['optimizely'].data.experiments[experimentId].name;
    // Use the experimentName and variationName value here to send information to your analytics platform

  }
}
</script>

Where indicated in the above code snippet, implement the platform specific code.

4. QA integration

When the integration is successfully implemented, check your network traffic to see if all the data is correctly send to the analytics platform. All the active experiments on the page in addition to a redirect experiment should be visible in the network traffic.

Mobile analytics

Mobile analytics integrations allow customers to track Optimizely experiments in an external analytics tool. Optimizely can append experiment data to analytics tracking code, so customers can see the impact of their experiments in their analytics tool. The following step-by-step guide describes how to implement an analytics integration for mobile through Optimizely provided plugins.The plugins allow you to capture information about which experiment is running and which variant is chosen for a visitor.

Prerequisites

1. Create a test application and install the Optimizely SDK

To get started, create a test application and install the Optimizely SDK. This is the app you’ll test your integration on. To learn how to install the Optimizely SDK, check out this step-by-step guide in our knowledge base.

2. Declare a dependency on the Optimizely SDK

To get started, declare a dependency on the Optimizely SDK in your test app. Declaring the dependency in Android happens by adding provided ("com.optimizely:optimizely-core:1.2.1+@aar") {transitive = true}to your build.gradle. You can read more about using Gradle to declare the dependency in the developer documentation for Android. For iOS you need to declare the dependency by adding pod 'Optimizely-iOS-SDK' to your CocoaPods Podfile. You can read more about using CocoaPods to declare the dependency in the developer documentation for iOS.

3. Implement the Optimizely plugin

Android

The Optimizely Android SDK includes an interface called "OptimizelyPlugin" that you will need to implement. This is an example implementation of the OptimizelyPlugin interface:

package com.analytics;

import com.optimizely.Optimizely;
import com.optimizely.integration.DefaultOptimizelyEventListener;
import com.optimizely.integration.OptimizelyEventListener;
import com.optimizely.integration.OptimizelyExperimentData;
import com.optimizely.integration.OptimizelyPlugin;

import org.json.JSONObject;

import java.util.List;

import android.app.Application;
import android.content.Context;
import android.support.annotation.NonNull;
import android.support.annotation.Nullable;
import android.view.View;

/**
 * Example Plugin
 */
public class ExamplePlugin implements OptimizelyPlugin {

    @NonNull
    @Override
    public String getPluginId() {
        return "com.example.plugin";
    }

    /**
     * Declare all required permissions here. Nullable lists are okay for the empty set of permissions.
     * @param context the context of the app in case the permission is based on the package name
     *                or otherwise declared via manifest.
     * @return a list of permissions required or null if no permissions are necessary
     */
    @Nullable
    @Override
    public List<String> getRequiredPermissions(Context context) {
        return null; // Declare required Android permissions
    }

    /**
     * Declare all dependencies on other plugins here.
     * @return
     */
    @Override
    public List<String> getDependencies() {
        return null; // Declare any dependencies on other Optimizely Plugins
    }

    /**
     * @return a touch listener which will receive all touch events that occur on tracked views
     */
    @Nullable
    @Override
    public View.OnTouchListener getOnTouchListener() {
        return null; // If your plugin wants to handle touch events, return an OnTouchListener here.
    }

    /**
     * @return a lifecycle callbacks that will receive all Android lifecycle events that occur
     */
    @Nullable
    @Override
    public Application.ActivityLifecycleCallbacks getActivityLifecycleCallbacks() {
        // If your plugin wants to be notified of Activity start/stop, return an
        // ActivityLifecycleCallbacks instance here.
        return null;
    }

    /**
     * @return a listener that will receive all events emitted by Optimizely and its plugins
     */
    @Nullable
    @Override
    public OptimizelyEventListener getOptimizelyEventsListener() {
        return mListener;
    }

    /**
     * Initialize the plugin and start any listeners or threads.
     * @param optimizely reference to the Optimizely singleton so that services can be accessed
     * @return true if the plugin was started successfully, false otherwise.
     */
    @Override
    public boolean start(Optimizely optimizely, JSONObject config) {
        return true;
    }

    /**
     * Stop the plugin and clean up any objects that are owned by the plugin.
     */
    @Override
    public void stop() {

    }

    /**
     * Interface for clients which want notifications when various Optimizely events occur.
     * Listeners are weakly held, so you may need to re-register your listeners if you don't
     * hold onto them.
     */
    private OptimizelyEventListener mListener = new DefaultOptimizelyEventListener() {
        /**
         * Notification that is fired whenever the user's experience has been affected
         * by an experiment. This means that:
         *   a live variable has been evaluated,
         *   a code block has been evaluated,
         *   or a visual change has been seen by the user.
         * @param experimentState the current running state of the experiment.
         */
        @Override
        public void onOptimizelyExperimentVisited(OptimizelyExperimentData experimentState) {
            String propertyName = "Optimizely: " + experimentState.experimentName;
            String propertyValue = experimentState.variationName;
            // mySDK.setGlobalProperty(propertyName, propertyValue);
        }

        /**
         * Notification that a goal has been triggered.
         * @param description A description of the goal event
         * @param affectedExperiments the experiments that are active and tracking this goal
         */
        @Override
        public void onGoalTriggered(String description, List<OptimizelyExperimentData> affectedExperiments) {
            String eventName = "Optimizely: " + description;

            for (OptimizelyExperimentData experimentData : affectedExperiments) {
                String propertyName = "Optimizely: " + experimentData.experimentName;
                String propertyValue = experimentData.variationName;
                // mySDK.setEventProperty(propertyName, propertyValue);
            }
            // mySDK.trackEvent(eventName);
        }
    };
}

The plugin framework offers a lot of functionality, but for most analytics integrations the functions in the OptimizelyEventListener shown in the example are sufficient.

onOptimizelyExperimentVisited

The function onOptimizelyExperimentVisited is triggered every time an experiment is shown to a user of the app. Every experiment has an ID and a name.The user will be randomly assigned to a variation of the experiment which also has an ID and a name. For the analytics integration, you'll want to use the experiment name and variation name. In the example, the experiment name is stored in the String propertyName and the variation name is stored in propertyValue. Both the experiment name and variation name are assigned to a user. Use your analytics SDK or REST API to append this metadata to a user. An example of how to send the data with the Google Analytics Android SDK is by using custom dimensions.

onGoalTriggered

The onGoalTriggered function is called everytime a goal that has been set in Optimizely is triggered by the user of the app. The onGoalTriggered function can be used to forward events to your SDK or REST API.

iOS

The Optimizely iOS SDK includes a interface called "OptimizelyPlugin" that you will need to implement. This is an example implementation of the OptimizelyPlugin interface:

//
//  ExamplePlugin.m
//
//  Created by Josiah Gaskin on 2015-10-08.
//

#import <Foundation/Foundation.h>
#import <Optimizely/OptimizelyPlugin.h>

@interface ExamplePlugin : NSObject<OptimizelyPlugin>

@end
OptimizelyRegisterPlugin(ExamplePlugin)

@implementation ExamplePlugin

/**
 * Return the plugin ID
 */
- (NSString *)pluginId {
    return @"com.example.analytics";
}

/*
 * iOS plugins are expected to handle their own permission requests appropriately
 */

/**
 * Declare all dependencies on other plugins here.
 * @return a list of plugin identifiers
 */
- (NSSet *)getDependencies {
    return nil;
}

/**
 * @return true if this plugin should receive and handle touch events
 */
- (BOOL)shouldHandleTouchEvents {
    return NO;
}

/**
 * If shouldHandleTouchEvents returns true, touch events will be passed to the plugin.
 */
- (void)processTouchEvent:(UIEvent *)event {}

/*
 * iOS plugins are expected to handle UIApplication* notifications as needed
 */

/**
 * iOS plugins can subscribe to the NSNotification center notifications for the Optimizely
 * notifications listed in Optimizely.h#NSNotification Keys
 */

/**
 * Initialize the plugin and start any listeners or threads.
 * @param optimizely reference to the Optimizely singleton so that services can be accessed
 * @return true if the plugin was started successfully, false otherwise.
 */
- (BOOL)startWithOptimizely:(Optimizely *)optimizely withConfig:(NSDictionary *)config {
    /**
     *  Constant NSNotification key that is triggered when an experiment is viewed by the user. The userInfo in the notification
     *  will have metadata which includes experiment Id, variation Id, experiment description and variation description. For more
     *  information on visited experiments, see the `visitedExperiments`.
     */
    [NSNotificationCenter.defaultCenter addObserverForName:OptimizelyExperimentVisitedNotification object:nil queue:nil usingBlock:^(NSNotification * _Nonnull note) {
        NSDictionary *userInfo = note.userInfo;
        NSString *property_name = [NSString stringWithFormat:@"Optimizely: %@", userInfo[@"experiment_id"]];
        NSString *property_value = userInfo[@"variation_id"];
        // [mySDK setGlobalProperty: property_value forKey: propertyName];
    }];

    /**
     *  Constant NSNotification key that is triggered when an Optimizely goal is triggered. The userInfo in the notification
     *  will have metadata which includes an array of experiments pertaining to this goal and the goal description. This notification
     *  is only fired in normal mode when a conversion is counted for 1 or more experiments.
     */
    [NSNotificationCenter.defaultCenter addObserverForName:OptimizelyGoalTriggeredNotification object:nil queue:nil usingBlock:^(NSNotification * _Nonnull note) {
        NSDictionary *userInfo = note.userInfo;
        NSString *description = userInfo[@"description"];
        NSArray *experiments = userInfo[@"experiments"];

        for (NSDictionary *experiment in experiments) {
            NSString *property_name = [NSString stringWithFormat:@"Optimizely: %@", experiment[@"experiment_id"]];
            NSString *property_value = experiment[@"variation_id"];
            // [mySDK setEventProperty: property_value forKey: propertyName];
        }
        // [mySDK trackEvent: description];
    }];
    return YES;
}

/**
 * Stop the extension and clean up any objects that are owned by the extension.
 */
- (void)stop {}

@end

The plugin framework offers a lot of functionality, but for most analytics integrations the observers in the startWithOptimizely:(Optimizely *)optimizely withConfig:(NSDictionary *)config function are most relevant.

OptimizelyExperimentVisitedNotification

The function OptimizelyExperimentVisitedNotification is triggered every time an experiment is shown to a user of the app. Every experiment has an ID and a name and the user will be randomly assigned to a variation of the experiment which also has an ID and a name. You need to use the experiment name and variation name for your analytics integration.In the example, the experiment name is stored in the NSString property_name and the variation name is stored in property_value. Both the experiment name and variation name are assigned to a user. Use your analytics SDK or REST API to append this metadata to a user. An example of how to send the data with the Google Analytics iOS SDK is by using custom dimensions.

OptimizelyGoalTriggeredNotification

The OptimizelyGoalTriggeredNotification function is called every time a goal that has been set in Optimizely is triggered by the user of the app. The OptimizelyGoalTriggeredNotification function can be used to forward Optimizely goal events to your SDK or REST API.

4. Enable plugin

The code that you wrote in step 3 needs to be enabled to become effective. If you used the plugin id "example_plugin", you need to use Optimizely.whitelistPlugin("example_plugin", null); to enable the plugin in Android and [Optimizely whitelistPlugin:@"example_plugin"]; on iOS. Once your integration gets approved for the Optimizely dashboard, you can skip this step. On iOS, your users will need to include the header file (e.g. ExamplePlugin.h) which contains your registration macro (the call to OptimizelyRegisterPlugin()). On Android, your plugin will be detected by the classloader.

5. QA integration

When the integration is successfully implemented, check your network traffic to see if all the data is correctly sending to the analytics platform. You can use Charles for monitoring your Network traffic. There is a configuration guide for using Charles with iOS and Android.

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 and periodically send audiences to Optimizely in the background. 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 an Optimizely audience

You can now create Audiences using the REST API. When a user indicates that they want to use an audience from your platform within Optimizely you should create an audience without conditions in Optimizely. Learn more on how to create audiences in Optimizely using the REST API.

An example of the Optimizely REST API call and the result with CURL is displayed here:

In the above picture, the REST API call returns various fields, including an id (highlighted with an arrow). You will need to use the id in the next step.

5. Add visitors to an audience

The Optimizely JavaScript API allows you to programmatically add a visitor to an Optimizely audience. To do so, you can use the following function:

window['optimizely'] = window['optimizely'] || [];
window['optimizely'].push(['addToAudience', audienceId]);

When you created the Optimizely audience in the previous step, you received an audience ID. You can use that ID in the JavaScript call.

6. QA your integration

To verify that the integration works, select an audience within your platform that you are sure you will be in. Trigger the procedure to create a corresponding Optimizely audience.

Verify that the audience creation has worked by going to https://app.optimizely.com/projects/{{ project_id }}/audiences. The audience that has been created should show up in the list.

When the audience is in the list, create and start an experiment that uses the audience. Go to your Experiment Dashboard and click on New Experiment. Open the Audience Builder (shown below) in the Optimizely Editor.

In the audience builder click on "Add a Saved Audience". Select the create audience and click on "add".

Go to the test page you have created. Verify that the experiment is running when the uploading of the experiment is done (approximately 2 minutes after saving an experiment). You can verify if the experiment is running by doing a hard refresh on the test page. Open the JavaScript console and execute optimizely.activeExperiments. The console will output an array with your experiment ID.

If you are sure the experiment should be running (after a few minutes) but doesn't show up in the activeExperiments array, it could be that the visitor has not been added to the Optimizely audience. You will get more information by executing optimizely.push("log").

Verify with your platform that you are recognised as being in the audience. You can verify that the Optimizely integration works by opening the JavaScript console and executing optimizely.data.visitor.audiences. The value of the audience ID that you created should be true.

Uploaded Lists

Uploaded List integrations allow customers to upload a list of user identifiers (e.g. cookies, query parameters, or other user identifiers) to Optimizely from a 3rd party application. These identifiers can be used to target experiments and segment results. Unlike audience integrations which operate client-side, user list integrations are implemented by a server-to-server exchange. For more information on uploaded lists, please refer to the Optimizely knowledge base.

This section walks you through how to build an integration that sends lists of users to Optimizely via the REST API. To see examples of Uploaded list integrations, check out our documentation on integrations with Salesforce and Marketo.

Prerequisites

1. Create a developer account

Uploaded Lists are a feature restricted to select Enterprise customers and developers. If you do not have access to Uploaded Lists and would like to develop an integration, create a free developer account. Creating a developer account does not require a credit card and will provide full access to the Uploaded Lists feature and associated APIs.

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 and periodically send lists to Optimizely in the background. Learn how to connect to Optimizely using OAuth 2.0.

3. Create a list in Optimizely

You can now send lists to Optimizely via the REST API. Note that we currently limit list sizes to 5MB. If you want to send larger lists, please submit a ticket to the developer support team with more information, including what size lists you hope to send via the API. Learn how to create an uploaded list in Optimizely via the REST API.

An example of the Optimizely REST API call and the result with CURL is displayed here:

4. Update a list in Optimizely

If you'd like periodically refresh your lists, please use the update endpoint to update an existing list.

5. QA your integration

To test the integration end-to-end, you should verify that the lists you've created via the API appear in the Uploaded Lists tab in Optimizely. You can download the lists directly from this interface to make sure the individual user IDs are uploaded as expected. Finally create an audience that includes the uploaded list and run an experiment that targets that audience to make sure that users are bucketed correctly.

Note: You may upload lists as frequently as you like. However, it may take up to 2 hours to propagate your lists to our servers.

Content Management

Content Management integrations allow customers to leverage the full power of Optimizely on a platform that manages content. Customers can create, configure, and run experiments directly from their content platform interface without having to login to Optimizely.

There are many types of content management integrations. The example below describes an integration that tests article headlines in WordPress. Other potential integrations include: testing images from within an e-Commerce platform, testing product titles from within an e-Commerce platform, and testing an entire article from an editorial platform.

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 and periodically send lists to Optimizely in the background. Learn how to connect to Optimizely using OAuth 2.0.

3. Create a configuration form: authentication and project selection

Users can authenticate your application to use the REST API using OAuth 2.0. You can find a description on how to implement OAuth authentication here.

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

You can see an example of how the configuration form should look like in the image below. The first step is to authenticate with Optimizely (the blue button). After the authentication is done, the user will be able to select a project from the selector below "Choose a project". The options within the project are populated by the information that is returned by the list-projects REST API call.

4. Create a configuration form: URL targeting

Because there are many different places on a page where an article can appear, the best URL targeting condition for a content management experiment is a substring match on the entire website. You can create an option that allows customers to select different URLS to target. This targeting will be used for all experiments that are created with the content testing tool.

5. Create a configuration form: variation code

For Optimizely to modify the right content on the page, users must be able to specify where the target content can be found. Create an HTML textbox that allows the user to specify the variation code.

6. Create an experiment

On the content item level, create a form that allows editors to create an experiment.

In the form that is added on a content item level, create fields that allow a user to fill in alternate titles for the article.

Sample HTML code:

<h1>Variation#1</h1>
<input type="text" id="post_title1" class="optimizely_variation" placeholder="AlternateTitle1">
<h1>Variation#2</h1>
<input type="text" id="post_title2" class="optimizely_variation" placeholder="AlternateTitle2">
<a id="optimizely_create" class="button-primary">CreateExperiment</a>

With the REST API you can create the experiment. In the screenshot you see that a user has the ability to fill in two alternate titles. This means that the created experiments should have 2 + 1 (for the original) variations. The variation code of the variations is defined by the setting in Step 5. and the values of the fields in the above form. If we consider the following scenario:

The variation code that you should use to create the variation using the REST API is:

Original // nothing to do here

Variation #1 $(".optimizely-423").text("Hello Mars!");

Variation #1 $(".optimizely-423").text("Hello Friends!");

If the article has a specific URL, like www.example.com/articles/article-$POST-ID, you can use the REST API to create a pageview goal for the experiment. You can read more about pageview goals here.

The REST API calls you'll use:

7. Start and pause experiment

After clicking the "Create experiment" button, the form on the content will change to allow a user to start, pause and modify the experiment.

You can use the REST API to update an experiment and a variation.

To start and pause the experiment, update the "status" field on an experiment to the value "Running".

8. Display results

For editors to work entirely in the content platform, you will also need to report the results of the experiments in the platform.

Results can be fetched using the get experiment results function of the REST API.

Conversion Tracking

Conversion Tracking integrations allow customers to use custom events (e.g. phone calls) as goals for their experiments, as opposed to default goals like clicks and pageviews. These integrations use Optimizely’s custom event goals functionality to track conversions. To see examples of Conversion Tracking integrations, check out our documentation on DialogTech or FreeSpee integrations.

This section walks you through how to create a conversion tracking integration using custom event goals and the offline conversion API.

1. Create a custom event goal

In order to track conversion events in Optimizely, a custom event goal needs to be defined. The custom event goal will be used to identify conversion events. It is possible to create multiple custom event goals for each type of conversion. Each custom event goal has a unique name that can be referenced in your application.

There are two ways you can create a custom event goal:

2. Reference custom event goal in your application

You'll need to reference the name of the custom event goal that was defined in Step 1. If the customer is creating the custom event goal manually prompt the user to enter the name of the custom event goal in your application (e.g. phone_call_conversion).

If you created the custom event goal using the REST API, use the value you chose for the "event" field.

3. Collect information about the visitor

In addition to the providing a custom event goal name, you'll also need to specify information about the visitor so Optimizely knows how to tie the conversion event back to the experiment and variation that was shown. All of this information can be fetched from a browser using the JS API. For convenience, we've provided some helper functions that you can use to collect all of the necessary information:

Project ID

/**
 * Gets the Optimizely Project ID installed on this page (sometimes the same as the Account ID)
 *
 * @return {Number} the project id
 */
function getProjectId() {
    return optimizely.getProjectId();
}

Experiment and Variation IDs

/**
 * Gets the experiment/variation mappings for the current visitor
 *
 * @return {String} a string that displays all the experiments and variations in a list of query parameters
 */
function getVariationsInParameters() {
    var variations = JSON.parse(decodeURIComponent(getCookie("optimizelyBuckets")));
    resultstring = "";
    for (var variation in variations) {
        resultstring += "&x" + variation + "=" + variations[variation];
    }
    return resultstring;
}

Segment IDs

/**
 * Gets the segment values for the current visitor
 *
 * @return {String} a string that displays all the segments and their values in a list of query parameters
 */
function getSegmentsInParameters() {
    var segments = JSON.parse(decodeURIComponent(getCookie("optimizelySegments")));
    var resultstring = "";
    for (var seg in segments) {
        resultstring += "&s" + seg + "=" + segments[seg];
    }
    return resultstring;
}

User IDs

/**
 * Getting the user ID is only possible using the cookie value
 *
 * @return {String} a JSON formatted string that contains all the segments and their values
 */
function getUserId() {
    return getCookie("optimizelyEndUserId");
}

4. Create an offline conversion

Once you know the required information about a visitor and the name of the custom event goal you want to track, you can create an offline conversion using a GET request in this format:

http://{{ project_id }}.log.optimizely.com/event
                               ?a={{ project_id }}
                               &n={{ goal identified }}
                               &u={{ Optimizely user id }}
                               &x{{experiment id 1}}={{variation id 1}}
                               &s{{segment id 1}}={{segment value 1}}

To learn more about the expected format of these parameters see Tracking offline conversion events with Optimizely.

The following function can be used to construct a valid offline conversion URL using the sample JavaScript functions above:

/**
 * Generate the entire URL that you can use to create a conversion, given a goalname. The goalname
 * is required, if you also provide a value, there will be a revenue value added to the conversion
 * call. The goalname will be encoded if it isn't already.
 *
 * @param {String} goalname (the goal were you are creating a conversion for)
 * @param {Number} value (a value representing the revenue of the conversion)
 * @return {String} a JSON formatted string that contains all the segments and their values
 */
function generateConversionUrl(goalname, value) {
    var goalname = decodeURIComponent(goalname) == goalname ? encodeURIComponent(goalname) : goalname;
    var result = "http://" + getProjectId() + ".log.optimizely.com/event?a=" + getProjectId() + "&n=" + goalname + "&u=" + getUserId() + getVariationsInParameters() + getSegmentsInParameters();
    if (typeof (value) != "undefined") {
        result += "&v=" + value;
    }
    return result;
}

5. QA your integration

To verify that the integration works, create an Optimizely experiment that includes the custom event goal in question. Then send visitor test traffic through your experiment and fire the offline conversion goals. Check your results page for the experiment. It should now include data on how many visitors and offline conversions have occurred for this experiment.

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 wether the snippet integration is working correctly by going to the test page on the website and opening the JavaScript console. When you execute optimizely.getProjectId() Optimizely should return the project ID that is installed on the page.