Event API

Intro

The Event API allows developers to send impression or conversion event data to Optimizely from anywhere. Our JavaScript API and mobile SDKs include out-of-the-box tracking for impressions and conversion events on your site or app, but you might want to send conversion data that occurs offline or server-side. In cases like this, event calls may be sent directly to Optimizely's logging servers. Let’s walk through the details!

Endpoint Structure

All conversion events are communicated to Optimizely via GET requests to log.optimizely.com/event with the form:

http://{project_id}.log.optimizely.com/event

Note: HTTPS is also supported.

Sending Conversion Data

The Event API can be used to send conversion goals to Optimizely. See below for the expected parameters for conversion goals.

Parameter Overview

Logging conversion event data follows this format:

http://1234567.log.optimizely.com/event?a=1234567
                               &n=example_event
                               &u=1316548451038r0
                               &x87654321=1111111
                               &v=500
                               &g=1234567
                               &d=8511325
                               &s983745985=gc
                               &time=1462472175

Parameter Reference

Definitions

a

Project ID. This is your project ID. It can be found in the web dashboard or in your Optimizely snippet.
<script src="//cdn.optimizely.com/js/{project_id}.js"></script>

x

Experiment/Variation mapping. These parameters specify which experiments and corresponding variations a given visitor has seen. Every call must inform Optimizely what experiment and variation a visitor was a part of. If a user is a part of multiple experiments you can specify multiple parameters as shown below.

Single Experiment:
x{experiment_id}={varation_id1}

Multiple Experiments:
x{experiment_id1}={varation_id1}&x{exeriment_id2}={varation_id2}

Developers must maintain their own bucket mapping by sending Optimizely the exposed experiment, as well as each variation the visitor has seen (or bucketed into). If you're tracking events for an Optimizely web project these mappings may be found in the "optimizelyBuckets" cookie, whose value is of the following form: %7B%22987654321%22%3A%221111111%22%2C%22876543210%22%3A%222222222_3333333%22%7D
or, after applying decodeURIComponent().

If you're ever curious what these IDs are for a given experiment, you can always find them by navigating to the Optimizely Editor, then selecting Options > Diagnostic Report.

n

Event Key. The unique string that identifies the conversion event. For web projects, this is the Custom Event To Track field.

Custom Event Field Screenshot
d

Account ID. Your Optimizely account ID. This can be found in account settings.

u

User ID. A unique user identifier for tracking and bucketing.

On web, our client uses a cookie to track the user and generates a unique user_id that is also stored in the cookie. Similarly, on iOS & Android the SDKs leverage a similar method for tracking users.

g
(Optional)

Goal ID. Each goal in your project has a unique goal ID. The can be fetched through the REST API. You can send multiple goals to Optimizely in the same request. Let’s say you have the goals “landed on a page” and “cart checkout”. Both of these goals can be triggered by a single event, so you would send an array of goals IDs back to Optimizely. Ex: g=12345,4324234

v
(Optional)

Goal Value. An integer denoting the value of your goal. Within Optimizely, every goal can have a value associated. For example, if your goal is revenue, the monetary value $5.00 is represented by v=500.

time
(Optional)

Timestamp. Timestamps can be provided using the parameter timestamp in epoch time in seconds. This is helpful if conversions are not sent in real time and have been recorded previously. Optimizely will then correctly backdate these events. Ex: time=1461708557

Other Considerations

Give it a try

Let’s build our own GET request to test this endpoint. We can confirm the data has been received by viewing the experiment results.

Appendix (Advanced)

Sending Impression Data

Our Event API also supports sending impressions, in addition to conversion events --although this isn’t necessary unless you are building for another channel like a custom server-side solution.

Within Optimizely an impression is logged when a visitor is bucketed into an experiment variation . Simply put, the visitor has met the criteria for the experiment and has been exposed to a variation. On the web, an impression would translate to a page view. This concept is a bit more complicated on other channels. For example, we decide to run an experiment on our search algorithm targeted to Japanese users. An impression is logged when a Japanese user interacts with the search algorithm and is successfully bucketed into a variation. An impression becomes a conversion event when the visitor completes a goal. In our example, the visitor uses the search algorithm to find flights and completes a booking (the conversion event).

Again, our web and mobile products handle impressions out of the box, so tracking them explicitly would only be necessary when building on other channels. To do so, you must set the goal_id to the experiment_id. It’s important to note that each unique visitor will count towards your MUV limit.

Example:

 http://1234567.log.optimizely.com/event?a=1234567
                               &n=example_event
                               &u=1316548451038r0
                               &x987654321=1111111
                               &g={experiment_id}
                               &d=8511325

If you have any questions, you can ask the developer community, or you can submit a ticket to the developer support team. We'll be happy to assist you.