Get started

For a complete description of the Event API, consult the Event API reference.

Step 1. Create an experiment

Re-use an existing experiment or create an 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 information on how to create an experiment, see the following documentation:

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 (projects created after February 2021):

• Quickstarts
• Run A/B tests
• Choose metrics
• Create events

Full Stack Experimentation (Legacy) (projects created before February 2021 or selected Use legacy experience during project creation):

• Quickstarts
• Run A/B tests
• Choose metrics
• Create events

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 end-user support article, Find IDs for API calls, to locate these fields.

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.

❗️

Warning

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 the campaign_id, experiment_id, and variation_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's entity_id is mapped to the corresponding variation's campaign_id as given in the decisions array.
• The enrich_decisions field set to true to enable Optimizely's Experimentation Events Export functionality. For information about this field, see the Event API reference. Also, see How Optimizely Experimentation counts conversions.

📘

Note

• The campaign_activated event must have a timestamp 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 one campaign_id, experiment_id, and variation_id triplet.
• You do not need to activate a user if they have already been activated by a Full Stack Experimentation or Web Experimentation activate() call.

The example includes the optional client_name and client_version fields. Include these fields for debugging.

{
  "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 variations.

See the Activate users section in this article for information about the client_name, client_version, and enrich_decisions fields shown in the example below.

You should include attributes for conversion events. Adding attributes will let you segment your results properly.

📘

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 related campaign_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
}

See the Event API reference for required and optional fields.

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, and enrich_decisions fields shown in the preceding code sample.

Step 5. Verify results

You will see the data reflected on the results page within a few minutes. To debug common issues, see Troubleshoot the Event API.