Overview

This page is a full reference for Optimizely's SDKs.

Read below to learn how to install one of our SDKs and run experiments in your code. You can use the toggles on the upper-right to see implementations in other languages.


If you're just getting started, we recommend the links below:


Example usage

The code at right illustrates the basic usage of the SDK to run an experiment in your code.

First, you need to initialize an Optimizely client based on your Optimizely project's datafile.

To run an experiment, you'll want to activate the experiment at the point you want to split traffic in your code. The activate function returns which variation the current user is assigned to. The activate function also sends an event to Optimizely to record that the current user has been exposed to the experiment. In this example, we've created an experiment my_experiment with two variations control and treatment.

You'll also want to track events for your key conversion metrics. In this example, there is one conversion metric, my_conversion. The track function can be used to track events across multiple experiments, and will be counted for each experiment only if activate has previously been called for the current user.

Note that the SDK requires you to provide your own unique user IDs for all of your activate and track calls. See User IDs for more details and best practices on what user IDs to provide.


Installation


Datafile

The SDKs are required to read and parse a datafile at initialization.

The datafile is in JSON format and compactly represents all the instructions needed to activate experiments and track events in your code without requiring any blocking network requests. For example, the datafile displayed on the right represents an example project from the Getting started guide and the basic usage above.

Unless you are building your own SDK, there shouldn't be any need to interact with the datafile directly. Our SDKs should provide all the interfaces you need to interact with Optimizely after parsing the datafile.

Access datafile via CDN

You can fetch the datafile for your Optimizely project from Optimizely's CDN. For example, if the ID of your project is 12345 you can access the file at the link below:

https://cdn.optimizely.com/json/12345.json

You can easily access this link from your Optimizely project settings.

Access datafile via REST API

Alternatively, you can also access the datafile via Optimizely's authenticated REST API. For example, if the ID of your project is 12345 you can access the file at:

https://www.optimizelyapis.com/experiment/v1/projects/12345/json

Please note that as with other requests to the REST API, you will have to authenticate with an API token and use the preferred request library of your language.


Synchronization

In order to receive experiment updates, the SDK needs to periodically synchronize the datafile from Optimizely.


Webhooks

If you are managing your datafile from a server-side application, we recommend configuring webhooks to maintain the most up-to-date version of the datafile. Your supplied endpoint will be sent a POST request whenever the respective project is modified. Anytime the datafile is updated, you must re-instantiate the Optimizely object in the SDK for the changes to take affect.

You can setup a webhook in your project settings and add the URL the webhook service should ping.

The webhook payload structure is shown at right. As of today, we support one event type, project.datafile_updated.


Versioning

Note: Datafile versioning is only provided for iOS, tvOS and Android projects.

For iOS, tvOS and Android projects, the datafile is versioned so that we can maintain backwards compatibility with SDKs that have been released out into the wild with older versions of the datafile. This will ensure that in the event our datafile schema changes, experiments will still run in apps that have not been updated with the latest version of the SDK.

All versions of the datafile for your Optimizely project are accessible via the CDN. For example, if the ID of your project is 12345 you can access v3 the datafile at the link below:

https://cdn.optimizely.com/public/12345/datafile_v3.json

We will upload every supported version of the datafile to our CDN so that SDKs that are pegged to an older version will be able to retrieve a datafile that is compatible with that SDK.

If you are using OPTLYManager (for iOS or tvOS) or OptimizelyManager (for Android) to manage datafile updates, these will gracefully handle datafile versioning. However, if you are managing the datafile on your own, then you have to make sure to fetch the correct version of the datafile according to the SDK version you are using.


Optimizely client


Initialization options

See SDK configuration for full details on how you can customize your Optimizely client.


Experiments

Use the activate function to run an experiment at any point in your code.

The activate function requires an experiment key and a user ID. The experiment key should match the experiment key you provide when setting up the experiment in the Optimizely web portal. The user ID is a string to uniquely identify the participant in the experiment (read more in User IDs below).

The activate function returns which variation the current user is assigned to. If the experiment is running and the user satisfies audience conditions for the experiment, the function returns a variation based on a deterministic murmur hash of the provided experiment key and user ID. This function also respects whitelisting and and user profiles.

Make sure that your code adequately deals with the case when the experiment is not activated i.e. execute the default variation.

The activate function also sends an event to Optimizely to record that the current user has been exposed to the experiment. You should call activate at the point you want to record an experiment exposure to Optimizely. If you don't want to record an experiment exposure, you can use an alternative function below to get the variation.


User attributes

If you'd like to be able to segment your experiment data based on attributes of your users, you should include the optional attributes argument when activating experiments. Optimizely will include these attributes in the recorded event data so you can segment them on the Optimizely results page.

Passing attributes will also allow you to target your experiments to a particular audience you've defined in Optimizely. If the provided experiment is targeted to an audience, Optimizely will evaluate whether the user falls in an audience that is associated with the experiment before bucketing.

For more information on managing audiences and attributes, see our Optiverse article.

Variation assignments

If you would like to retrieve the variation assignment for a given experiment and user without sending a network request to Optimizely, use the code shown on the right. This function has identical behavior to activate except that no event is dispatched to Optimizely.

You may want to use this if you're calling activate in a different part of your application, or in a different part of your stack, and you want to fork code for your experiment in multiple places. It is still necessary to call activate at least once to register that the user was exposed to the experiment.


Events

You can easily track conversion events from your code using the track function.

The track function requires an event key and a user ID. The event key should match the event key you provided when setting up events in the Optimizely web portal. The user ID should match the user ID provided in the activate function.

The track function can be used to track events across multiple experiments, and will be counted for each experiment only if activate has previously been called for the current user.

To enable segmentation of metrics on the Optimizely results page, you'll also need to pass the same user attributes you used in the activate call.

Note: The Optimizely experiment results page will only count events that are tracked after activate has been called. If you are not seeing results on the Optimizely results page, make sure that you are calling activate before tracking conversion events.


Event tags

Event tags are contextual metadata about conversion events that you track.

You can use event tags to attach any key/value data you wish to events. For example, for a product purchase event you may want to attach a product SKU, product category, order ID, and purchase amount. Event tags can be strings, integers, floating point numbers, or Boolean values.

You can include event tags with an optional argument in track as shown on the right.

Event tags are distinct from user attributes which should be reserved for user-level targeting and segmentation. Event tags do not affect audiences or the Optimizely results page, and do not need to be registered in the Optimizely web interface.

Event tags are accessible via raw data export in the event_features column. You should include any event tags you need to reconcile your conversion event data with your data warehouse.

Reserved tags

The following tag keys are reserved and will be included in their corresponding fields in the Optimizely event API payload. They're bundled into event tags for your convenience. Use them if you'd like to benefit from specific reporting features such as revenue metrics.

  • revenue - An integer value that is tracked in aggregate as an experiment metric. Revenue is recorded in cents: if you'd like to record a revenue value of $64.32 use 6432.


Tracking with other SDKs

You can use any of our SDKs to track events, so you can run experiments that span multiple applications, services, or devices. All of our SDKs have the same bucketing and targeting behavior so you'll see the exact same output from experiment activation and tracking, provided you are using the same datafile and user IDs.

For example, if you're running experiments on your server you can activate experiments with our Python, Java, Ruby, C#, Node, or PHP SDKs, but track user actions client-side using our JavaScript, Objective-C or Android SDKs.

If you plan on using multiple SDKs for the same project, make sure that all SDKs are sharing the same datafile and user IDs.


User IDs

User IDs are used to uniquely identify the participants in your experiments. You can supply any string you wish for user IDs depending on your experiment design.

For example, if you're running experiments on anonymous users, you can use a 1st party cookie or device ID to identify each participant. If you're running experiments on known users, you can use a universal user identifier (UUID) to identify each participant. If you're using UUIDs then you can run experiments that span multiple devices or applications and ensure that users have a consistent treatment.

User IDs don't necessarily need to correspond to individual users. If you're running experiments in a B2B SaaS application, you may want to pass account IDs to the SDK to ensure that every user in a given account has the same treatment.

Below are some additional tips for using user IDs.

  • Ensure user IDs are unique: It is essential that user IDs are unique among the population you are using for experiments. Optimizely will bucket users and provide experiment metrics based on this user ID that you provide.

  • Anonymize user IDs: The user IDs you provide will be sent to Optimizely servers exactly as you provide them. You are responsible for anonymizing any personally identifiable data such as email addresses in accordance with your company's policies.

  • Use IDs from 3rd party platforms: If you are measuring the impact of your experiments in a 3rd party analytics platform, we recommend leveraging the same user ID from that platform. This will help ensure data consistency and make it easier to reconcile events between systems.

  • Use one namespace per project: Optimizely generally assumes a single namespace of user IDs for each project. If you are using multiple different conventions for user IDs in a single project (e.g. anonymous visitor IDs for some experiments and UUIDs for others) then Optimizely will be unable to enforce rules such as mutual exclusivity between experiments.

  • Use either logged-out vs. logged-in IDs: We do not currently provide a mechanism to alias logged-out IDs with logged-in IDs. If you are running experiments that span both logged-out and logged-in states (e.g. experiment on a signup funnel and track conversions after the user has logged in), you must persist logged-out IDs for the lifetime of the experiment.


Variables

Use Live Variables to parameterize your app with features you'd like to experiment with in real-time.

Variables can be declared and initialized once in your app. After deploying those variables to production, you can subsequently run unlimited experiments on different values of those variables without doing another code deploy. Variables can be controlled from the Optimizely UI so you can roll out features and tweak the behavior of your app in real-time. See our Optiverse article for more details on how to control variables from the Optimizely user interface.


Exclusion groups

You can use Exclusion Groups to keep your experiments mutually exclusive and eliminate interaction effects. For more information on how to set up exclusion groups in the Optimizely UI, see our Optiverse article.

Experiments that are part of a group have the exact same interface in the SDK: you can call activate and track like any other experiment. The SDK will ensure that two experiments in the same group will never be activated for the same user.


Whitelists

You can use Whitelisting to force users into specific variations for QA purposes. For more information on how to set up whitelists in the Optimizely UI, see our Optiverse article.

Whitelists are included in your datafile in the forcedVariations field. You don't need to do anything differently in the SDK; if you've set up a whitelist, experiment activation will force the variation output based on the whitelist you've provided. Whitelisting overrides audience targeting and traffic allocation. Whitelisting does not work if the experiment is not running.


IP anonymization

In some countries, you may be required to remove the last block of an IP address to protect the identity of your visitors. Optimizely allows you to easily remove the last block of your visitors' IP address before we store results data. This feature is currently available only for iOS, tvOS, and Android projects. To enable IP anonymization, see our Optiverse article.


SDK configuration

You can optionally provide a number of parameters to your Optimizely client to configure how the SDK behaves:

  • Event dispatcher: Configure how the SDK sends events to Optimizely
  • Logger: Configure how the SDK logs messages when certain events occur
  • Error handler: Configure how errors should be handled in your production code
  • User profile: Configure what user state is persisted by the SDK

The SDK provides default implementations of event dispatching, logging, and error handling out of the box, but we encourage you to override the default behavior if you have different requirements in your production application. If you'd like to edit the default behavior, refer to the reference implementations in the SDK source code for examples.


Event dispatcher

You can optionally change how the SDK sends events to Optimizely by providing an event dispatcher method. You should provide your own event dispatcher if you have networking requirements that aren't met by our default dispatcher.

The event dispatching function takes an event object with three properties: httpVerb, url, and params, all of which are built out for you in EventBuilder. A POST request should be sent to url with params in the body (be sure to stringify it to JSON) and {content-type: 'application/json'} in the headers.

Logger

The logger logs information about your experiments to help you with debugging.

The log levels vary slightly between SDKs but generally fall in the following buckets:

Log level            Description
CRITICAL Events that cause the app to crash are logged.
ERROR Events that prevent experiments from functioning
correctly (e.g., invalid datafile in initialization,
invalid experiment keys or event keys) are logged.
The user can take action to correct.
WARNING Events that don't prevent experiments from functioning
correctly, but can have unexpected outcomes (e.g.,
future API deprecation, logger or error handler are
not set properly, nil values from getters) are logged.
DEBUG Any information related to errors that can help us
debug the issue (e.g., experiment is not running, user
is not in experiment, the bucket value generated by
our helper method) are logged.
INFO Events of significance (e.g, activate started,
activate succeeded, tracking started, tracking
succeeded) are logged. This is helpful in showing the
lifecycle of an API call.


Error handler

You can provide your own custom error handler logic to standardize across your production environment. This error handler will be called in the following situations:

  • Unknown experiment key referenced
  • Unknown event key referenced

If the error handler isn’t overridden, a no-op error handler is used by default.


User profile

Use a user profile to persist information about your users and ensure variation assignments are sticky. For example, if you are working on a backend website, you can create an implementation that reads and saves user profiles from a Redis or memcached store.

Implementing a user profile service is optional and is only necessary if you want to keep variation assignments sticky even when experiment conditions are changed while it is running (e.g. audiences, attributes, variation pausing, traffic distribution). For more information on user profiles and how they used by the SDK, see this Optiverse article.


Debugging

You can plug in a logger to assist with debugging. In addition, below are options for debugging with the SDK.


Notification Listeners

You can use notification listeners to be notified when various Optimizely X SDK events occur.


Integrations

You can add Optimizely experiment information to third-party analytics platforms using Notification Listeners. Measure the impact of your experiments by segmenting your analytics reports using Optimizely experiment and variation keys or IDs.

Below you will find suggested implementations for some common analytics platforms including Amplitude, Google Analytics, Localytics, Mixpanel, and Segment. You can use them as presented or adapt them to meet your specific needs.

Notification Listeners also allow for the flexibility to implement an integration with a platform that is not listed here.

Experiment and Variation Identifiers

Experiment keys are unique within an Optimizely project, and variation keys are unique within an experiment. However, experiment and variation keys are not guaranteed to be universally unique since they are user generated. This may become a problem in your analytics reports if you use the same key in multiple Optimizely projects or rename your keys.

For human friendly strings when absolute uniqueness is not required, use keys. If you need to uniquely identify experiments and variations in a way that will not change when you rename keys, you can use the automatically generated IDs.


Amplitude


Google Analytics


Localytics


Mixpanel


Segment

Please refer to the Optimizely X Fullstack guide for instructions on integrating our JavaScript SDK with your Segment analytics.


Changelog