Log commerce events

This is for:

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

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

There are two main approaches to collecting analytics data: the direct client-side approach and the tag management approach using data layers. The tag management approach logs events through services like Google Tag Manager, Tealium, and Adobe Launch. This tag management approach reduces the amount of page loading time and decreases maintenance. For an introduction, see the Implement commerce event tracking course.

Libraries

To build your product discovery interfaces, we recommend using the Coveo UI libraries (Coveo Atomic and Coveo Headless) because they automatically send analytics events.

In particular, the Coveo Headless Commerce controllers automatically log specific commerce events that track behaviors, such as when a purchase is made or when a product is added to a cart. Upcoming Atomic Commerce components will also automatically send analytics events.

Note

If you use the Headless Commerce engine, use its controllers to log commerce events, even if you have an existing tag management solution in place. Headless automatically logs events for you, so using both Headless and a tag management system may result in duplicate events, which can affect your reporting metrics. Relying on multiple systems to log events can lead to unexpected results and make troubleshooting harder.

Under the hood, Headless Commerce controllers and forthcoming Atomic Commerce components use the Event Protocol to log events. Previous implementations used the Coveo UA Protocol.

Use the Event Protocol for new Coveo for Commerce implementations as it simplifies event tracking by reducing the number of events you need to send to Coveo. It simplifies event tracking by reducing the number of events you need to send to Coveo. The protocol simplifies the event payload by requiring fewer fields and eliminating optional ones.

For existing implementations, continue with the Coveo UA Protocol as content is developed to assist in your migration to the new Event Protocol.

Tracking protocol comparison

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