Client ID FAQ

The client ID is a UUID which is generated in the browser by the Coveo UA library. Coveo services can use it to identify a specific browser and device combination. The client ID doesn’t identify a human user, as two human users may use the same browser, and a single human user may interact with Coveo across multiple devices. The client ID also needs to be stored inside the browser to ensure that it maintains the same value during different sessions.

The third-party cookie deprecation didn’t initiate the migration to the client ID. Older versions of Coveo stored an identifying variable in a server-provided third-party cookie. The decision to deprecate this method of persistence by 2023 was made to respect compliance goals, and also in response to browser evolution where many browsers began blocking access to third-party cookies.

The migration to the client ID began in early 2021 as a new way to identify browsers being used on Coveo-powered search interfaces. Note that once the third-party cookie deprecation is complete, storing and sending the client ID from the browser will become an essential tracking mechanism.

The client ID and its associated code and documentation meet HIPAA requirements and they apply for both HIPAA and non-HIPAA Coveo organizations, as well as related Coveo-powered digital experiences. The client ID is a randomized globally unique id which does not contain any personal information.

Over time, there have been different versions of the UUID standard. The client ID can be a UUID of any version, as long as it’s valid in that specific version.

The latest Coveo OOTB (out-of-the-box) frameworks (Atomic, Headless, JavaScript Search Framework, and Quantic) generate the client ID. To maintain a consistent client ID across browser sessions, the client ID is stored in the browser’s local storage (under visitorId) and as a first-party cookie (under coveo_visitorId). These values should always be identical, but should they differ, the local storage value will take precedence.

We don’t recommend using session storage (sessionStorage method) instead of local storage.

Session storage is cleared when the browsing session ends, whereas local storage doesn’t expire. If session storage is used instead, then Coveo Usage Analytics (Coveo UA) events wouldn’t be able to unify the actions between multiple browser sessions, multiple browser tabs, or multiple browser windows on that domain since a new client ID would be generated each time. If you alter code to leverage session storage, this would be considered custom code, which could consequently lead to breaking changes when upgrading to new Coveo framework versions.

You may notice that there’s a drop in the number of anonymous visits once you’re using the client ID. This is because when a user is anonymous, the unique ID dimension uses the client ID instead of the visitor ID to obtain a picture of the unique visitor count. Once the client ID is generated, the Visit Browser shows the unique user ID.

No, the visit ID isn’t affected. The visit ID represents a single visit, which ends after 30 minutes of inactivity.

Yes, when present, the client ID becomes the tracking identifier for the user visit. This is expected, because the client ID stitches events together and ensures that a single visit is registered.

That depends on your exact domain setup. If your digital experiences leveraging Coveo traverse multiple top-level domains (for example, a.com and b.com), then work will be required to develop code to generate the same client ID on each digital experience. Increased privacy features on browsers no longer allow different domains to read each other’s storage. If your digital experience leveraging Coveo traverses different subdomains with the same top-level domain (for example, www.a.com and shop.a.com), the client ID will remain consistent.

When sending an event, if no client ID is provided, Coveo UA generates a visitor ID instead, which is then returned in the response.

For collect events however, only the client ID is supported. Therefore, if one isn’t provided, a HTTP 400 error is returned.

The transition to using the client ID won’t directly impact Coveo Machine Learning (Coveo ML). However, not upgrading to a more recent version of the Coveo JavaScript Search Framework may affect how Coveo UA events are recorded. This will have an impact on Coveo Machine Learning (Coveo ML) from user actions (search, click, and view).

The various Coveo ML models are configured to use OOTB (out-of-the-box) model configurations that aren’t affected by the move to the client ID.

For the moment, you may still see the name visitorId in the browser’s local storage (and coveo_visitorId in the first-party cookie). These variables have been historically used to persist the Coveo-computed visitorId. These will eventually be identified as clientId once we’ve determined that the change in naming won’t break existing integrations.