Get started

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

Create an experiment

Reuse an existing experiment, or create a new experiment in the Optimizely application and add at least one event and metric. Start the experiment before proceeding to the next step. For information on how to create an experiment, see the following documentation:

Optimizely Web Experimentation and Optimizely Performance Edge experiments

• Steps to create an experiment in Optimizely Web Experimentation or Performance Edge
• Create an experiment in Optimizely Performance Edge (developer guide)
• Configure events in Optimizely Experimentation
• Create a metric in Optimizely Experimentation

Optimizely Feature Experimentation experiments

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

Collect the required identifiers

The following table shows the required fields for the JSON object described in the Build the JSON data object section.

To locate these fields, follow the instructions in Find IDs for API calls.

Build the JSON data object

The JSON data object structure differs depending on whether you are activating a user or tracking a conversion event.

❗️

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, which represents the visitor being assigned 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 feature. 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 earlier 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 Feature 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.

When enrich_decisions is true, Optimizely retains the activation information for each visitor (campaign_id, experiment_id, and variation_id) and automatically matches subsequent conversion events to the correct variation.

See the Activate users section for information about the client_name, client_version, and enrich_decisions fields in the following code example.

Include attributes for conversion events. Adding attributes lets you segment your results properly.

📘

Note

• You still need to pass an empty decisions array, as shown in the following example.
• 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 are deduplicated. It is not sufficient to have only a unique entity_id. Each event needs 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.

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

The API does not require an authorization token. The following is a sample cURL request.

After the API receives your request, it queues the JSON payload for processing and returns a 204 status code.

🚧

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 the Activate users section for information about the client_name, client_version, and enrich_decisions fields shown in the preceding code sample.

Verify results

Results typically display on the Experiment Results page within a few minutes. To debug common issues, see Troubleshoot the Event API.