Get started
This topic describes how to set up and get started with the Optimizely Event API
For a complete description of the Event API, consult the Event API reference.
Step 1. Create a new experiment
Re-use an existing experiment or create a new experiment in the Optimizely application and add at least one event and metric. Make sure you start your experiment before proceeding to the next step.
For Optimizely Web Experimentation and Optimizely Performance Edge experiments:
- Six steps to create an experiment in Optimizely Web Experimentation
- Create an experiment in Optimizely Performance Edge
- Set up events in Optimizely Experimentation
- Create a metric in Optimizely Experimentation
For Optimizely Feature Experimentation experiments:
Full Stack Legacy (projects created before February 2021):
Optimizely Feature Experimentation (projects created after February 2021):
Step 2. Collect the required identifiers
The table below shows the required fields to include in the JSON object described in step 3, Build the JSON data object.
Follow the instructions in the Support article, How to locate IDs for the Optimizely Event API, to locate these fields.
Field | Type | Required to activate user | Required to track event |
---|---|---|---|
account_id | account identifier | Yes | Yes |
visitor_id | visitor identifier | Yes | Yes |
timestamp | event timestamp | Yes | Yes |
entity_id | event entity identifier | Yes | Yes |
campaign_id | campaign assignment(s) | Yes | No |
experiment_id | experiment assignment(s) | Yes | No |
variation_id | variation assignment(s) | Yes | No |
Step 3. Build the JSON data object
The JSON data object structure differs depending on whether you want to activate a user to a variation or track conversion events.
Note
A single JSON object must be 3.5 MB or less.
Activate users
To activate a user to a variation, send a JSON object that includes:
- The
decisions
array, containing thecampaign_id
,experiment_id
andvariation_id
. - The
events
array, containing a special event of type,campaign_activated
that represents the visitor being bucketed to a particular variation. By convention, this event'sentity_id
is mapped to the corresponding variation'scampaign_id
as given in thedecisions
array. - The
enrich_decisions
field set totrue
to enable Optimizely Experimentation's Enriched Events Export functionality. For more information about this field, see the Event API reference. See also How Optimizely Experimentation counts conversions.
Note
- The
campaign_activated
event must have atimestamp
equal to or older than other tracked conversion events, as explained in How Optimizely Experimentation counts conversions. Any conversion events with timestamps older than the related decision event will not be counted on the Results page.- A single visitor can only be exposed to one variation of one experiment within a campaign. Ensure that each
campaign_activated
event for a given visitor is mapped to only onecampaign_id
,experiment_id
andvariation_id
triplet.- You do not need to activate a user if they have already been activated by a Full Stack or Web
activate()
call.
The example includes the optional client_name
and client_version
fields. We recommend that you include these fields for debugging purposes.
{
"account_id": "1887578053",
"visitors": [
{
"visitor_id": "test_user",
"snapshots": [
{
"decisions": [
{
"campaign_id": "9560823711",
"experiment_id": "5733750339",
"variation_id": "6630810318"
}
],
"events": [
{
"entity_id": "9560823711",
"type": "campaign_activated",
"timestamp": 1491519130343,
"revenue": 9900,
"uuid": "12a25c92-7edd1-1c30-21a8-aa4c850671e4"
}
]
}
]
}
],
"anonymize_ip": true,
"client_name": "Optimizely/event-api-demo",
"client_version": "1.0.0",
"enrich_decisions": true
}
Track conversion events
A conversion event represents a visitor taking a specific action on your site.
If enrich_decisions
is true, the activation information for each visitor is retained (meaning the campaign_id
, experiment_id
, and variation_id
). Subsequent conversion events are automatically matched to the appropriate variation(s).
See the Activate users section in this article for more information about the client_name
, client_version
, and enrich_decisions
fields shown in the example below.
Note
- You still need to pass an empty
decisions
array, as shown in the example below.- The conversion event must have a timestamp equal to or more recent than the timestamp of the
campaign_activated
event, as explained in How Optimizely Experimentation counts conversions. Any conversion events with timestamps older than the relatedcampaign_activated
event will not be counted on the Results page.- Within a session, events of the same UUID will be deduplicated. It is not sufficient to have only a unique
entity_id
. Each event will need a UUID to avoid deduplication.
{
"account_id": "your_account_id",
"visitors":
[
{
"visitor_id": "test_user",
"attributes": [],
"snapshots": [
{
"decisions": [],
"events": [
{
"entity_id": "1260528912",
"key": "test_event",
"timestamp": 1540996187279,
"uuid": "12a25c92-7edd1-1c30-21a8-aa4c850671e4",
"revenue": 10000
}
]
}
]
}
],
"anonymize_ip": true,
"client_name": "Optimizely/event-api-demo",
"client_version": "1.0.0",
"enrich_decisions": true
}
For more information about the required and optional fields, see the Event API reference.
Step 4. Send data object as POST call
After you build the JSON data object, send it to the following Event API endpoint
as a POST call: <https://logx.optimizely.com/v1/events
>.
There is no Authorization token requirement to use the API. Below is a sample cURL request.
After the API has received your complete call, it queues your JSON file for processing and returns a response with status code 204.
Important
The response does not indicate that your JSON has been validated. Consult the Event API reference for more guidance.
curl -X POST
-H "Content-Type: application/json" -d
"https://logx.optimizely.com/v1/events"
{
"account_id": "your_account_id",
"visitors":
[
{
"visitor_id": "test_user",
"attributes": [],
"snapshots": [
{
"decisions": [],
"events": [
{
"entity_id": "1260528912",
"key": "test_event",
"timestamp": 1540996187279,
"revenue": 10000,
"uuid": "12a25c92-7edd1-1c30-21a8-aa4c850671e4"
}
]
}
]
}
],
"anonymize_ip": true,
"client_name": "Optimizely/event-api-demo",
"client_version": "1.0.0",
"enrich_decisions": true
}
Note
See Activate users section for more information about the
client_name
,client_version
andenrich_decisions
fields shown in the preceding code sample.
Step 5. Verify results
Within a few minutes, you will see the data reflected on the Results page. If you do not, read the article on troubleshooting the Event API to debug common issues that can lead to unexpected results.
Updated 28 days ago