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 Coveo’s 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 Coveo Relay are currently in open beta. 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. Such streamlining results in a more efficient and less error-prone event tracking process, yielding better machine learning models and usage analytics reports.

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.

The Coveo Headless Commerce controllers automatically log Event Protocol events for you. Forthcoming Atomic Commerce components will do so as well, and so will Headless and Atomic v3 in general.

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, Coveo 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.