Track usage analytics

This is for:

Developer

To create reports and power Coveo Machine Learning models, it’s crucial to track user interactions within your search interfaces. You can do this by sending events to the Coveo Usage Analytics (Coveo UA) service.

We recommend using the Coveo search UI libraries (Coveo Atomic & Coveo Headless) because they automatically take care of sending many analytics events. When properly configured, these libraries automatically log many relevant events. If your implementation doesn’t use the recommended UI libraries or needs to send events not captured by them, you can use either the Event Protocol or Coveo UA Protocol.

The following table summarizes the two protocols, the front-end libraries you can use to send events, and the underlying API to which the events are sent to.

Important

By default, Coveo search UI libraries log usage analytics events even when end users reject cookies. You must implement a mechanism to prevent logging events when end users reject cookies. Not doing so pollutes your usage analytics data and affects data health.
Name Tracking library Underlying API

New

Event Protocol

Relay

Event API

Legacy

Coveo UA Protocol

coveoua

Usage Analytics Write API

Event Protocol

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).

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

It simplifies event tracking by reducing the number of events you need to send to Coveo. For instance, you no longer need to send any search events as they’re logged server-side when you make a request to the Search API.

The protocol also streamlines the event payload, requiring fewer fields and eliminating optional ones for clarity.

Event Protocol uses event schemas that define the fields you need to send for each event type. For more details on the schemas and the fields they require, see the Event API reference page.

Relay

Relay is the new tracking library for sending events using Event Protocol. Relay not only provides all the benefits of the protocol, it’s also lighter than the previous coveoua library.

Additionally, Relay seamlessly integrates with the Explorer Chrome extension. When activated, Explorer will validate sent events in real time, providing feedback on the analytics implementation.

Coveo UA Protocol

The Coveo UA Protocol is the original protocol used to send events to Coveo.

Compared to the event protocol, the Coveo UA Protocol is more verbose and requires more client-side tracking.

Coveo UA library (coveoua)

coveoua is the legacy tracking library, designed to send events to the Usage Analytics Write API.

Note

Keep in mind, for certain implementations, coveoua might be your only choice. We’re actively expanding the Event Protocol to encompass all use cases. At present, we support events for Commerce and basic search, with more use cases on the way.