Event Protocol

This is for:

Developer

The Event Protocol is a new standard for sending usage analytics events to Coveo.

Important

The EP and Coveo Relay library are generally available for Commerce.

However, they’re in closed beta for Coveo for Service, Website, and Workplace implementations. If you’re interested in using the Event Protocol and Relay library for these implementations, contact your customer success manager (CSM).

We highly recommend using Coveo Atomic, Coveo Headless or Coveo Relay, which wrap the complexity of the Event API, over using the Event API directly.

Search events

The Event Protocol doesn’t require you to log search events. When you send search requests to the Search API or the Commerce API, the API automatically logs the corresponding search events server-side.

Coveo Headless and Atomic use the Event Protocol by default as of v3, activating server-side logging of search events automatically.

Commerce API server event logging

You can also activate server-side event logging in the Commerce API by setting the context.capture parameter to true in your commerce queries.

{
  ...
  "context": {
    ...
    "capture": true, 1
  }
}
1 Activates server-side event logging.
Note

The context.capture parameter is currently true by default, but it will be false by default in a future release.

Search API server event logging

You can activate server-side event logging in the Search API by setting the analytics.capture parameter to true in your search requests.

If you do so, be sure to set the analytics.actionCause parameter. See Standard actions and UA reference.

For reporting purposes, also provide as many parameters exposed in the analytics object as possible.

Example:

{
  ...
  "analytics": {
    "capture": true, 1
    "actionCause": "searchboxSubmit", 2
    "clientId": "9dn3nd88-75ea-3b8d-93nq-1208a732cafc", 3
    "clientTimestamp": "2024-04-10T14:01:28.026Z",
    "documentReferrer": "default",
    "originContext": "Search",
    "documentLocation": "https://sports.barca.group/search",
    "documentReferrer": "default",
    "originContext": "Search"
  }
}
1 Activates server-side event logging.
2 Sets the action cause as specified in Standard actions and UA reference.
3 Additional parameters for reporting purposes.

Opting-in or out of tracking

You may need to provide users with the ability to opt-in or out of tracking, following the applicable privacy regulations (see Data tracking).

Server events

When you want to prevent search events from being used for analytics purposes, set the capture parameter to false in your search requests. When using the Commerce API, that’s the context.capture parameter, while in the Search API, it’s the analytics.capture parameter. Also, don’t send any data persisted in the browser, such as clientId, since it would constitute tracking.

Commerce API example

{
  ...
  "context": {
    "capture": false,
    ...
  }
}

Search API example

{
  ...
  "analytics": {
    "capture": false,
    ...
  }
}
Note

If you’re using the Coveo Headless Commerce controllers, see Disable and enable analytics.

Client events

Disabling and enabling client-side event logging depends on your implementation.

If you’re using Relay, see Relay: Opting-in or out of tracking.

If you’re using the Coveo Headless, see Disable and enable analytics.

If you’re using the Event API directly, make sure that your implementation logs events only after users have consented, or haven’t opted out of tracking, depending on the applicable privacy law.

What’s next?

If you’re using the Event Protocol for a commerce implementation, see Event Protocol for commerce.

To track events using the Relay library, see the Relay library documentation.