Event Protocol with Headless

This is for:

Developer
Important

Event Protocol is currently in open beta. If you’re interested in using Event Protocol, reach out to your Customer Success Manager (CSM).

Since the Headless V3 release, EP is the default tracking protocol.

Important

Only Coveo for Commerce supports EP at the moment. For every other kind of implementation, set analyticsMode to legacy for the time being.

 
const engine = buildSearchEngine({
    configuration: {
        // ...rest of configuration
        analytics: {analyticsMode: 'legacy'},
    }
})

To learn more about whether you should migrate to EP, see Migrate to Event Protocol.

Log events

EP is simpler to use and more streamlined than the legacy Coveo UA protocol. EP doesn’t support custom events, custom data, or custom context. Search events are sent server-side, so you don’t need to log them client-side. Headless controllers, when used correctly, also log click events for you.

As a result, you generally won’t need to tinker with search or click events yourself.

Warning

We strongly recommend using the InteractiveResult controller when implementing your result components. The controller can automatically extract relevant data from result items and log click events for you, as in the following interactive example.
Note

For the purpose of using content recommendations models however, you must log view events. Headless controllers won’t log view events for you. Use the Relay library.

Disable and enable analytics

Coveo front-end libraries use the coveo_visitorId cookie to track individual users and sessions.

Note

Coveo now uses the client ID value to track individual users and sessions. For compatibility with legacy implementations, however, the associated cookie and local storage value are still labeled visitorID.

When implementing a cookie policy, you may need to disable UA tracking for end-users under specific circumstances (for example, when a user opts out of cookies). To do so, call the disableAnalytics method on an engine instance.

To re-enable UA tracking, call the enableAnalytics method.

// initialize an engine instance
const headlessEngine = buildSearchEngine({
  configuration: getSampleSearchEngineConfiguration(),
});

headlessEngine.disableAnalytics()
// Or, headlessEngine.enableAnalytics();

doNotTrack property

doNotTrack is a browser property which reflects the value of the DNT HTTP header. It’s used to indicate whether the user is requesting sites and advertisers not to track them.

Note

This property is deprecated, but it’s still supported in many browsers.

Headless v2 complies with the value of this property. It automatically disables analytics tracking whenever DNT is enabled.

Important

Headless v3 will no longer support this property.

To understand how Coveo Usage Analytics tracks users and sessions, see What’s a user visit?.