Data tracking

This is for:

System Administrator

Coveo’s Hosted Services leverage user data to provide core features such as Coveo Usage Analytics (Coveo UA) and Coveo Machine Learning (Coveo ML). Reliable and continuous tracking of a user’s interactions with the platform is critical for deriving insights and personalizing search results.

However, data tracking also affects user privacy. Consequently, browser and mobile platform vendors are making it increasingly harder to provide consistent user identifiers across different web domains.

As a result, Coveo is deprecating third-party cookies and has implemented a way for clients to send a client ID through the Coveo UA Write API, when logging UA events. The client ID is a unique value generated by the Coveo UA library that identifies a browser client on a Coveo-powered search interface. It’s usually kept client-side in local storage.

Note

If you aren’t using the Coveo UA library, you can still send the client ID by adding it to the payload on the call to the UA Write API.

Corporate position on tracking

Coveo respects legal requirements around tracking and personalization. This means that any integration is required to obtain user consent before tracking, or the user should be provided with a possibility to opt out, depending on the applicable privacy law. This is commonly done with a cookie pop-up banner and preference center.

Note

Coveo isn’t responsible for showing this cookie pop-up. This lies with the integrating party.

For information on the steps to take when tracking is rejected, see What should I do if users on my website don’t consent to be tracked?

Additional privacy preference signals

In addition to the regular opt-in or opt-out mechanisms with cookie banners/pop-ups, you might also want to consider supporting additional privacy preference signals, such as:

  • doNotTrack: a browser property which reflects the value of the DNT HTTP header. It sends a signal to websites requesting them not to track the user’s online activity.

    Historical Coveo client-side libraries automatically honored the DNT header by default. However, Relay, Headless v3 and Atomic v3 will leave it up to the implementer to decide whether to support individual privacy signals, based on their specific legal and business requirements.

  • globalPrivacyControl^: a new browser property which reflects the value of the Sec-GPC HTTP header. It aims to provide a standardized way for users to indicate their privacy preferences and is explicitly recognized by some privacy laws as a valid opt-out mechanism.

Tracking identifiers in use

Coveo gathers two pieces of information for tracking interactions:

Client ID

The client ID is a v4 UUID which represents a distinct browser on the current top-level domain. It’s generated client-side, at page initialization, by the hosting page. It’s sent as part of the event payload and is also included in relevant calls to other Coveo backend services. Older integrations may refer to it as Visitor ID instead.

User ID

The user ID is a human-readable identifier representing a distinct entity, typically through an email address or login name. The user ID is known whenever a user authenticates with the hosting application. It can be used to track users across applications and domains, and can potentially contain personally identifiable information (PII).

Current tracking methods in use

All technical tracking capabilities are currently provided by the Coveo client-side libraries, which include Coveo components and packages (for example, the Coveo JavaScript Search Framework or Coveo Headless library).

Top-level domains

Coveo’s base product tracks anonymous users within the same top-level domain, but doesn’t track anonymous users across different top-level domains. If cross-domain tracking is required by your implementation and you’re in control of both domains, we can provide tools and guidance for setting up tracking across domains (see Customize data tracking).

Example

Under Coveo’s default settings, an anonymous user visits http://www.fashionunion.com, and then navigates to http://store.fashionunion.com. The user has a persisting client ID since both sites are within the same top-level domain.

However, when they visit http://www.sportsactive.com next, their client ID is different because it’s under a different domain.

Local storage and cookies

As of February 2020, version 2.16.2 (and higher) of the Coveo UA library writes a UUID clientId into the local storage (when available) and also sets a session cookie (if allowed). Local storage carries no expiration date and the value will persist until the user deletes it. Its limitation is that it can only be read from the exact subdomain in which the entry was created.

The session cookie only persists the value for the current browsing session across subdomains. As of January 2023, in the 2.24.0 version of the Coveo UA library, first-party cookies have an expiration date and can be queried across subdomains. By default, when the Coveo UA library is running on a domain (for example, http://www.a.b.com), it will try to persist a first-party cookie with an expiration of one year for the entire top-level domain (for example, b.com).

Note

Certain browsers enforce expiration limits for first-party cookies that are lower (for example, Safari has an expiration limit of seven days) and may ignore or override Coveo’s default expiration limit.

The active value of the clientId will always be replicated to both the local storage and first-party cookie storage mechanisms if possible. The value persisted in the browser’s local storage takes precedence if both a local storage and a cookie value are present.

Important

The clientId value can be found in a sites' local storage with the attribute name visitorId, and in the first-party cookie storage with the attribute name coveo_visitorId, instead of the expected name, clientId. See the Client ID FAQ for more information.

Limitations

Limitations to Coveo’s out-of-the-box (OOTB) tracking capabilities:

  • Coveo can’t track users across many top-level domains without client specific adjustments, as described earlier in the article. This behavior is intended.

    Note

    If this is an issue, you can create your own tracking identifier and provide it to Coveo.

  • Once a user deletes their cookies and clears local storage, we lose their tracking data. If a user revisits the same website, they will effectively be a new user. This behavior is intended.

  • A client-generated client ID shouldn’t contain personally identifiable information (PII).

FAQ

Are Coveo cookies first-party or third-party cookies?

Coveo exclusively uses first party cookies. Third-party cookies are no longer supported.

What are the leading practices when choosing tracking technologies?

Coveo recommends that preference should be given to first-party cookies and local storage. If you choose to rely on other tracking mechanisms, you should ensure that it’s used in compliance with privacy laws.

Coveo cookies are usually classified as functional or performance/analytics cookies.

In that scenario, you should disable logging of usage analytics data. Depending on your implementation, see the following documentation to enable or disable usage analytics tracking: