Migrate to Event Protocol

This is for:

Developer

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.

We strongly recommend using the Event Protocol in new implementations and for existing Coveo UA implementations with poor Data Health (platform-ca | platform-eu | platform-au). Other implementations should consider migration on a case by case basis. Depending on your current implementation, the process can vary:

  • If you use the Coveo Headless or Coveo Atomic libraries, they will support the Event Protocol by default in the upcoming V3 release, as the Headless Commerce controllers already do. In the meantime, you can also use EP with those libraries by setting the Engine analyticsMode property to next at initialization.

    Atomic example
    const searchInterface = document.querySelector('atomic-search-interface');

await searchInterface.initialize({
    // ...
    analytics: {analyticsMode: 'next', trackingId: 'sports'},1
});
// ...
    1 Also make sure to set the trackingId property.
    Note

    The Coveo JavaScript Search Framework doesn’t support EP. We recommend migrating to Atomic or Headless.

  • If you use the Search API directly, capture search events server-side, or, in a Commerce context, use the Commerce API.

  • If you use the Usage Analytics Write API directly, migrate to the Event API (see EP reference).

  • If you use the Coveo UA library to log events, use the Relay library.

But before migrating to the Event Protocol, it’s important to understand why certain Coveo UA functionalities are no longer supported by the new Event Protocol. This article goes over those differences and how they affect your migration.

Custom events, custom data, and custom context

EP doesn’t support custom events or customData within events (for example, Search event customData). EP limits support for custom context.

Rather than supporting these, EP rather consolidates the common use cases into more streamlined and efficient event schemas. This yields cleaner data, which in turn yield more powerful ML models and usage analytics reports.

Custom events

Under the Coveo UA protocol, custom events tracked user interactions that weren’t tracked by search and click events. The common use cases are covered by the EP event schemas, which are more streamlined and efficient than custom events. For example, requesting more facet values used to be tracked via custom events, but is now tracked via search events.

Some implementers also relied on custom events to track their own custom interactions, which they might have used in reports. Such custom events aren’t supported by EP, but common user interactions are covered by event schemas.

Custom data

Under the Coveo UA protocol, customData logged additional event information, some of which was leveraged by ML models, and some of which wasn’t. The commonly used custom data is now covered by the more streamlined EP event schemas or are inferred automatically.

For example:

  • customData.context_website has been replaced by trackingId in Commerce schemas.

  • customData.group is inferred automatically.

Custom context

EP offers limited support for custom context, which was previously supported by the Coveo UA protocol and leveraged for reporting or ML.

Client events

In contrast with the Coveo UA protocol, the Event Protocol doesn’t support logging custom context. Certain Event Protocol schemas support a context parameter, but its format is fixed. That is, such context doesn’t let you specify custom keys.

Server events

Support for custom context in server events depends on the Coveo API providing a free-form context parameter. The Search API does expose such a free-form context parameter, allowing you to specify custom context in your search requests. The Search API includes this custom context in the corresponding search events it logs server-side. Coveo Machine Learning models can learn from this context, and you can also leverage it in query pipeline conditions or UA reports.

To send custom context in search requests, we recommend using Headless. If you use Atomic, use Headless through Atomic.

On the other hand, the Commerce API context parameter has a fixed structure and doesn’t support custom keys. That is, the Commerce API doesn’t support custom context.

Machine Learning

Due to the custom events, data, and context that are no longer supported, the following differences apply to Coveo ML models under EP:

If you used either of those functionalities and migrate to EP, adjust and test your ML models. Due to the more streamlined and efficient event schemas, the ML models should be more powerful under EP.

Reporting

Besides the fact that you can’t report on the custom events, data and context that’s no longer supported, EP reporting also differs from UA reporting due to search count differences. Every search request to the Search/Commerce API logs a search event, whereas the previous protocol sometimes logged custom events (for example, loading more results was previously tracked as a custom event).

This might cause a noticeable change in the clickthrough rate, because the denominator (search count) can be higher under the new protocol given the same user interactions. For example, if a user loads more results multiple times, the search count increases, which decreases the clickthrough rate under EP, whereas it would have remained constant under the previous protocol.

The goal of this reporting change is to align with the industry definitions for metric calculation.

Identifying users

To improve security, client-side specification of usernames is no longer supported. To specify usernames, enforce them through search tokens. This change makes it impossible for malicious actors to impersonate others in usage analytics events.

Finally, user stitching won’t be supported under EP initially, but will be supported in the future. It’s important to note that the user stitching support was limited in the first place, and that it will be improved under EP.