Getting started with the Events API

When integrating using REST APIs, you must use the Events API to track events and send them to Discover. In this integration option, the event object is the same as the one used with the runtime JS integration, except for some additional required keys.

The following table lists the additional keys required by the event object when making calls to the Events API, regardless of whether or not you use the Discover beacon:

Key	Type	Description
`user_id` OR `uuid`	string	Required. Anonymous user identifier. Note If beacon is present, use `rfk.uid()` to obtain `uuid`. If not, you must create your own `user_id`.
`t`	number	Required. Client (browser) epoch time, in milliseconds.
`t0`	number	Required. Page load epoch time (when page was loaded), in milliseconds.
`value.context.geo`	geo object	Required. The user's location information. Located in the event object.
`value.context.browser`	browser object	Required. The user's browser information. Located in the event object.

Note

Events submitted using the REST API do not include the actual HTTP headers of the user browsing the site. You must send these additional attributes about the user using the geo object and the browser object.

The following is an example of a widget event object in an Events API request:

RequestResponse

{    
  "value": {        
    "context": {            
      "page": {                
        "uri": "/catalogsearch/result"            
      },            
      "geo": {                
        "ip": "<user's IP address>"            
      },            
      "browser": {                
        "user_agent": "<user agent>"            
      }        
    },        
    "rfkid": "rfkid_7",        
    "f": "sp"    
  },    
  "type": "widget",    
  "name": "appear",    
  "t": 1625144306397,    
  "t0": 1625144306397,    
  "uuid": "<uuid obtained using rfk.uid()>"
}

Calling the Events API

Method: GET or POST

The following table lists the keys for the Events API request:

Key	Type	Description	Value
`data`	JSON string	Required. JSON representing the event object.
`json`	integer	Optional. Indicates whether to get pixel or JSON response.	0 - pixel response (default) 1 - JSON response

Key

Type

Description

Value

data

JSON string

Required.

JSON representing the event object.

json

integer

Optional.

Indicates whether to get pixel or JSON response.

0 - pixel response (default)

1 - JSON response

The following is an example of a GET request to the Events API:

RequestResponse

GET {EVENT_URL}?data={<event object>}

The following is an example of a POST request to the Events API:

RequestResponse

POST {EVENT_URL}
{
 "data": "{<event object>}"
}

The Events API and the Discover beacon

If you have included the Discover beacon on your site, you can take advantage of some of its functionality when integrating using REST APIs. The beacon takes care of the following considerations:

Anonymous user identifier - When using the Events REST API, the event object must include an anonymous user identifier that is used to track user behavior. If you include the Discover beacon on your site, Discover automatically creates a temporary, anonymous user ID (uuid )for each user. If you do not include the beacon, you must create your own user_id.
Product detail page views - When present, the Discover beacon automatically captures page view events and sends them to Discover. These events are converted to product views based on URI resolution. If you have not included the beacon on your site, product detail page view events are not automatically reported. You must therefore manually track pdp:view events.

Do you have some feedback for us?

If you have suggestions for improving this article,