Get started

9 min

For a complete description of the Event API, see the Event API referenceEvent 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 EdgeSteps to create an experiment in Optimizely Web Experimentation or Performance Edge

Create an experiment in Optimizely Performance EdgeCreate an experiment in Optimizely Performance Edge (developer guide)

Configure events in Optimizely ExperimentationConfigure events in Optimizely Experimentation

Create a metric in Optimizely ExperimentationCreate a metric in Optimizely Experimentation

Optimizely Feature Experimentation experiments

QuickstartsQuickstarts

Run A/B testsRun A/B tests

Choose metricsChoose metrics

Create eventsCreate 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 callsFind IDs for API calls.

Field	Type	Required to activate a 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	Yes	No
experiment_id	Experiment assignment	Yes	No
variation_id	Variation assignment	Yes	No

Build the JSON data object

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

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 referenceEvent API reference. Also, see How Optimizely Experimentation counts conversionsHow Optimizely Experimentation counts conversions.

The campaign_activated event must have a timestamp equal to or earlier than other tracked conversion events, as explained in How Optimizely Experimentation counts conversionsHow Optimizely Experimentation counts conversions. Any conversion events with timestamps older than the related decision event will not be counted on the results pageresults 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 resultssegment your results properly.

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

The response does not indicate that your JSON has been validated. Consult the Event API referencethe 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
  }

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 pageExperiment Results page within a few minutes. To debug common issues, see Troubleshoot the Event APITroubleshoot the Event API.