Event Protocol

This is for:

Developer
In this article

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

Important

The Event Protocol and Relay library are currently in early access. If you’re interested in using the Event Protocol and Relay library, reach out to your Customer Success Manager (CSM).

We highly recommend using the Relay library, which wraps the complexity of the Event API, over using the Event API directly.

Search events

In contrast with the Coveo UA protocol relying on the Usage Analytics (UA) Write API, the Event Protocol doesn’t require you to log search events. Rather, when you send search requests to the Search API or the Commerce API, the API automatically logs the corresponding search events server-side.

Server-side event logging is enabled by default in the Commerce API, and you don’t need to send any extra information for it to be properly configured.

Search API server-side event logging

Future releases of Coveo Headless and Atomic will use the Event Protocol by default. The libraries will handle server-side event logging for you automatically.

In the meantime, in early access, 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.

Custom context

Client events

In contrast with the Coveo UA protocol, the Event Protocol doesn’t support logging custom context. Certain Event Protocol schemas support a context parameter, but its format is fixed. That is, such context doesn’t allow you to specify custom keys.

Server events

Support for custom context in server events depends on the Coveo API providing a free-form context parameter. The Search API does expose such a free-form context parameter, allowing you to specify custom context in your search requests. The Search API includes this custom context in the corresponding search events it logs server-side. Coveo Machine Learning models can learn from this context, and you can also leverage it in query pipeline conditions or UA reports.

On the other hand, the Commerce API context parameter has a fixed structure and doesn’t support custom keys. That is, the Commerce API doesn’t support custom context.