Event Protocol
Event Protocol
The Event Protocol is a new standard for sending usage analytics events to Coveo.
|
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 Coveo Headless Commerce controllers or the Relay library, which wrap 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.
Commerce API server event logging
The Coveo Headless Commerce controllers automatically use EP by default. The library handles server-side event logging automatically, in the same way that it handles client-side search events automatically. Forthcoming Atomic Commerce components will do so as well, and so will Headless and Atomic v3 in general.
In the meantime, in early access, 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,
}
}
Activates server-side event logging. |
|
Note
The |
Search API server 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,
"actionCause": "searchboxSubmit",
"clientId": "9dn3nd88-75ea-3b8d-93nq-1208a732cafc",
"clientTimestamp": "2024-04-10T14:01:28.026Z",
"documentReferrer": "default",
"originContext": "Search",
"documentLocation": "https://sports.barca.group/search",
"documentReferrer": "default",
"originContext": "Search"
}
}
Activates server-side event logging. | |
Sets the action cause as specified in Standard actions and UA reference. | |
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.
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 Commerce controllers, 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.