The Full Stack Developer Guide Developer Hub

Welcome to the Full Stack Developer Guide developer hub. You'll find comprehensive guides and documentation to help you start working with the Full Stack Developer Guide as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Getting started

The steps below will walk through building a data object for the Event API. For a complete description of the Event API, consult the Event API reference.

1. Create a new experiment

Create a new experiment from your Optimizely project page and add at least one event and metric. Make sure you start your experiment before proceeding to the next step.

For Web experiments

2. Collect the required identifiers

The table below shows the required fields to include in the JSON object described in the next step, Build the JSON data object.

Follow the instructions in Knowledge Base article How to locate IDs for the Optimizely X Event API to locate these fields.

Field
Type
Required to activate user
Required to track event

account_id

account identifier

Y

Y

visitor_id

visitor identifier

Y

Y

timestamp

event timestamp

Y

Y

entity_id

event entity identifier

Y

Y

campaign_id

campaign assignment(s)

Y

N

experiment_id

experiment assignment(s)

Y

N

variation_id

variation assignment(s)

Y

N

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 10 MB or less.

Activate users

To activate a user to a variation, send a JSON object that includes:

  • The decisions array, which contains the campaign_id, experiment_id, and variation_id.
  • The events array, which contains 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 Easy Event Tracking functionality. For more information about this field, see the Event API reference. See also How Optimizely counts conversions.

Note that:

  • The campaign_activated event must have a timestamp equal to or older than other tracked conversion events, as explained in How Optimizely counts conversions. Any conversion events with timestamps older than the related decision event won't be counted in 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 don't need to activate a user if they've 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,
              "uuid": "3a427b02-7ae0-4b20-8f02-32cc8a067be4"
              "tags": {
            		"revenue": 9900
            	}
            }
          ]
        }
      ]
    }
  ],
  "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, Optimizely retains the activation information for each visitor (meaning the campaign_id, experiment_id, and variation_id). Subsequent conversion events are automatically matched to the appropriate variation(s).

See Activate users above for more information about the client_name, client_version, and enrich_decisions fields shown in the example below.

Note that:

  • 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 counts conversions. Any conversion events with timestamps older than the related campaign_activated event will not be counted in the Results page.
{
    "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
}

For more information about the required and optional fields, see the Event API reference.

4. Send data object as POST call

After you build the JSON data object, send it to the Event API as a POST call. There is no Authorization token requirement to use the API. Below is a sample cURL request.

After the API has receives your complete call, it queues your JSON file for processing and returns a response with status code 204.

Important

The response doesn't indicate that your JSON has been validated. Consult the Event API reference for more guidance.

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

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
  }
  
  

5. Verify results

Within a few minutes, you'll see the data reflected in the Results page. If you don't, read the troubleshooting section to debug common issues that can lead to unexpected results.

Updated about a year ago


Getting started


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.