Skip to main content

Track events

The Track Events API is used to capture a user's interaction following a query, such as impressions, clicking on a search result, or adding an item to a cart.

Event flow​

The following sequence diagram illustrates the typical flow for tracking events:


In the diagram above,

Steps 1–6 are the typical flow for tracking queries.

Steps 7–12 illustrate the event flow for capturing four events:

  1. Search Result impressions presented to the user.
  2. A click on a search result
  3. A search result is added to the cart.
  4. The cart is checked out.

Steps 7, 8, and 9 are sent from the user's browser using client-side JavaScript, authorized by a Site - typically with the browser tracker library. Step 11 is sent from the Application server-side.

Note

Events can be sent from client-side, server-side, or from both. Both use the same tracking endpoint, and every event must carry the site_id of a registered Site; browser submissions must additionally originate from one of that Site's allowed origins.

Event specification​

The OpenAPI specification contains the JSON schema for the event type, Event for the REST API.

The User Behavior Insights proto contains the proto messages for the gRPC API: TrackEventsRequest and TrackEventsResponse.

The schema follows Version 1.3.0 of the UBI specification.

Example​

The track event API accepts an array of events in a single request. A single event is sent as an array of one.

Here's an example request to the track event API:

{
    "events": [
        {
            "application": "primary-search",
            "site_id": "01JE0VN2Q6XZ9K7Y8ABCDEF01",
            "action_name": "click",
            "query_id": "01JE0VKZF8G03G7X16EDE6WNKJ",
            "session_id": "01JE0VM6029EVZT2SGHN1VYNAS",
            "client_id": "01JE0VHF3Q6ZAT2Y5R8KX0M4WN",
            "timestamp": "2024-12-01T00:00:00.0000000Z",
            "user_query": "men's warm winter coat",
            "event_attributes": {
                "object": {
                    "object_id": "sku001",
                    "object_id_field": "sku"
                },
                "position": {
                    "ordinal": 1
                }
            }
        }
    ]
}