Event Protocol with Headless

This is for:

Developer

In the upcoming Headless V3 release, the Event Protocol will be the default tracking protocol, as it already is with the Commerce engine. In the meantime, you can already use EP with Headless by setting the Engine analyticsMode property to next in the engine configuration, such as in the following example.

const headlessEngine = buildSearchEngine({
  configuration: {
    analytics: {analyticsMode: 'next', trackingId: 'sports'},
    //...
  },
});

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