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

Note

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

Privacy preferences

Coveo respects users' privacy preferences. When a user opts out of tracking or sends a do not track header with their requests, we won’t collect any analytics data. When a user clears their cookies, the Coveo Platform managing local storage won’t try to recreate them through other methods (for example, eTags, iFrames, or browser fingerprinting).

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 tracking identifier since both sites are within the same domain.

However, when they visit http://www.sportsactive.com next, since it’s under a different domain, their tracking identifier is different.

Tracking identifiers in use

Coveo gathers many 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. Contrary to the Coveo-assigned visitor ID, it’s sent as part of the event payload and is also included in relevant calls to other Coveo back-end services.

The client ID takes precedence over visitor ID, therefore the UA Write service won’t return a cookie containing the visitor ID value when it’s present. However, both options are still supported individually for calls to the Coveo UA endpoint.

Visitor ID

The visitor ID is a string identifier assigned to a visitor upon a first interaction with the UA endpoint. If no value is provided, a new identifier is created and returned both as an HTTP visitor cookie and as the visitorId property in the query response.

Note

Previous versions of the Coveo UA library relied solely on the visitor ID assigned by Coveo UA, which was then stored in a third-party cookie (that is, set by coveo.com on the client domain). Since third-party cookies are being phased out by major browser vendors, we recommend that you upgrade to a more recent version of the integration library as soon as possible.

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 UA library which includes Coveo components and packages (for example, the Coveo JavaScript Search Framework or Coveo Headless library). The key issue in tracking is persisting a tracking identifier across a user’s different browser sessions over time.

Depending on the version of the library, this persistence may be achieved with one of the following options:

Third-party cookies

Coveo UA previously relied on third-party cookies to store the visitorId, a random and unique value, to track users visiting a Coveo-powered website. This third-party cookie had the same value for Coveo as a first-party cookie, as we didn’t leverage the cross-site tracking functionality.

While the use of third-party cookies isn’t legally problematic, they do present a greater privacy risk. Therefore, many web browsers now block their creation by default or plan to stop their support.

Until all Coveo clients have migrated to client IDs which are stored in first party cookies, the Coveo analytics service will continue to send the third-party cookie on all requests. It can be found on the list of cookies for the webpage (name: visitor, domain: analytics.cloud.coveo.com).

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 domain (for example, http://www.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 visitor ID shouldn’t contain personally identifiable information (PII).

FAQ

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

Coveo is moving away from third-party cookies and is now using first-party cookies and local storage to store the client ID, which can be sent through the Coveo API when logging UA events.

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.

If your users don’t consent to be tracked, your Coveo organization administrator can disable Coveo UA. The Coveo JavaScript Search Framework has three functions which administrators can use to activate or disable Coveo UA, as well as to clear local session information from the browser.