What is the client ID?

Analyze Usage Data Coveo Relevance Cloud Business Analyst System Administrator Product Documentation

In this article

Advantages of using the client ID
Does my implementation pass the client ID?
Test the client ID
Reference

The client ID is a unique value generated by the coveo.analytics.js library that identifies a user on a browser of a Coveo-powered search page. It provides insight into the events they performed, and as a tracking ID, it provides accuracy on the number of unique visitors because it references the Unique Client Id metric.

The client ID is especially useful since users are often not authenticated and are therefore anonymous on websites. When a user is anonymous, Coveo uses the client ID to populate the unique user ID dimension. This can help you learn how many distinct users performed a query or opened an item, counting them only once even if the same search actions were recorded over the course of many visits.

By default, the client ID is supplied to Coveo Usage Analytics (Coveo UA) and kept in the local storage of the user’s browser.

Note

In the local storage, you may still see the visitorID value instead of the clientID. See Client ID FAQ for more information.

Advantages of using the client ID

While the client ID bears some similarities to the visitor ID, such as their longevity as well as their usefulness for gathering UA events, the client ID is preferred for several reasons.

For instance, it doesn’t rely on third-party cookies, which is an advantage since more and more browsers are blocking them.

Another reason to use the client ID is because it’s generated client-side, which gives the front-end control of the ID generation. This resolves race condition issues experienced with the visitor ID. These issues occur when there are multiple analytics scripts since the visitor ID is generated by Coveo UA. Furthermore, multiple visitor IDs can refer to the same anonymous user; while it’s possible to match them, it’s a time-consuming process.

Notes

When both the client ID and the visitor ID are present, Coveo UA selects the client ID to resolve the visit associated with an event. Furthermore, when the client ID is present, Coveo UA doesn’t return a cookie containing the visitor ID value.
When sending an event, if no ID is provided, Coveo UA generates a visitor ID. The generated ID is returned in the response.

Does my implementation pass the client ID?

To ensure that the client ID is being passed, it’s essential that the version of the Coveo JavaScript Search Framework (JSUI) used by your Coveo implementation is either the January 2021 version or a newer one. This is because as of January 2021, we implemented a mechanism for clients to send the client ID through the Coveo UA Write API - Version 15 in order to track user visits.

Note

If the coveo.analytics.js library isn’t used, you can still send the client ID by adding it to the payload on the call to the Coveo UA Write API - Version 15.

We recommend that you first verify which JSUI version you’re currently using. You can identify the version from either a search interface or from the distribution files.

If you’re using a version older than the January 2021 version, you must then upgrade to a newer one. We recommend upgrading to the latest version.
If you’re using the January 2021 version (or newer), then you don’t need to do anything further except test the client ID to ensure that it’s functioning properly.

Note

All Coveo Headless and Atomic integrations use the correct version of the library, therefore the client ID is sent.

For applicable Coveo integrations, the following table lists the January 2021 version upgrades:

Integration	Upgrade
Coveo for Salesforce	Upgrade to 4.13 (or higher).
Coveo for Sitecore	Upgrade to 5.0.943.3 (or higher).
Coveo for ServiceNow	Upgrade to 21.2.51 (or higher).
Coveo for Zendesk	Upgrade all search pages to 2.10083 (or higher).

Integration

Upgrade

Coveo for Salesforce

Upgrade to 4.13 (or higher).

Coveo for Sitecore

Upgrade to 5.0.943.3 (or higher).

Coveo for ServiceNow

Upgrade to 21.2.51 (or higher).

Coveo for Zendesk

Upgrade all search pages to 2.10083 (or higher).

Notes

The Coveo for Slack integration doesn’t require an upgrade as it was originally released after January 2021.
You also have the option to forego the integration upgrade, and instead upgrade your JSUI package to the January 2021 version (or newer) only. However, we still recommend a full package upgrade for Coveo for Sitecore 5 clients, because the January 2021 JSUI version may not be supported well by the latest package.
Although you can upgrade to the January 2021 version, we recommend upgrading to the latest version available to ensure optimal performance.

If you have a custom integration, in addition to using a newer JSUI version, you must also ensure that the entirety of your integration is up to date. For example, if you’re using a combination that includes the Collect endpoint, ensure that the client ID is being sent to both the Coveo UA and the Collect endpoints. Also ensure that you’ve removed the visitor ID tracking mechanism. Otherwise, visits will consequently be split in two and this will affect reporting accuracy.

Test the client ID

There are several ways to verify that your Coveo implementation is passing the client ID:

You can access the Visit Browser.
You can create a custom dashboard.
You can use your browser’s developer tools.

Visit Browser

You can use the Visit Browser (platform-eu | platform-au) in the Coveo Administration Console by sorting through events. For example:

Custom dashboard

You can create a Client ID verification dashboard.

On the Reports (platform-eu | platform-au) page, add a blank dashboard.
In the upper-right corner of the window, click , and then select Paste JSON configuration.
In the Import a Report Configuration panel that appears, paste this JSON configuration, and then click Import and save.
Adjust the date range to specify the date your upgrade was completed.
Inspect the report to ensure that the All events card and the Events sending a Client ID card are identical, with the same events and event counts, and that the Events leveraging a third-party cookie card is empty.

Developer tools

Use your browser’s developer tools to view the client ID.

Open a Coveo-powered search page.

Open your browser’s developer tools.

Notes

For instructions on using developer tools, depending on your browser, see:
This article uses the Google Chrome developer tools for its examples.

In the developer tools window, select the Network tab.
On the search page, perform a query to trigger an event.
Back in the developer tools window, under the Name column, click the latest call to Coveo UA.
Select the Payload tab, then, under the Request Payload section, expand the actionCause to view the client ID. For example:

Reference

To test whether your search interface sends your client ID, paste this code into the Import a Report Configuration panel when creating the Client ID verification dashboard.

{
 "displayName": "Client ID verification",
 "type": "DASHBOARD",
 "configuration": {
  "description": "This report is to validate that all events are sending the client ID.",
  "dateRange": {
   "range": "weeks",
   "length": 1,
   "offset": -1
  },
  "compareRange": {
   "range": "weeks",
   "length": 1,
   "offset": -2
  },
  "tabs": [
   {
    "id": "9487",
    "title": "Tab 1",
    "sections": [
     {
      "title": "",
      "position": {
       "col": "1",
       "row": "1",
       "sizex": "6",
       "sizey": "11",
       "minSizex": 2
      },
      "cards": [
       {
        "id": "7006",
        "href": "",
        "title": "All events",
        "sortBy": "DocumentView",
        "filters": "",
        "metrics": [
         "DocumentView",
         "CustomEvent",
         "PerformSearch"
        ],
        "cardType": "DetailedStatistics",
        "position": {
         "col": 1,
         "row": 2,
         "sizex": 4,
         "sizey": 4,
         "minSizex": 1,
         "minSizey": 2
        },
        "ascending": false,
        "showCount": false,
        "dimensions": [
         "customEventType",
         "originLevel1"
        ],
        "headerHref": "",
        "showHeader": true,
        "metricsSort": [
         "PerformSearch",
         "DocumentView",
         "CustomEvent"
        ],
        "metricFilters": "",
        "dimensionsSort": [
         "originLevel1",
         "customEventType"
        ],
        "metricsHeaders": {},
        "bindOnLastSearch": true,
        "dimensionsHeaders": {},
        "editMode": false
       },
       {
        "id": "34FF",
        "href": "",
        "title": "Events sending a Client ID",
        "sortBy": "DocumentView",
        "filters": "(clientid!~'null' AND clientid!~'' AND clientid!=null)",
        "metrics": [
         "DocumentView",
         "CustomEvent",
         "PerformSearch"
        ],
        "cardType": "DetailedStatistics",
        "position": {
         "col": 1,
         "row": 7,
         "sizex": 2,
         "sizey": 4,
         "minSizex": 1,
         "minSizey": 2
        },
        "ascending": false,
        "showCount": false,
        "dimensions": [
         "customEventType",
         "originLevel1"
        ],
        "headerHref": "",
        "showHeader": true,
        "metricsSort": [
         "PerformSearch",
         "DocumentView",
         "CustomEvent"
        ],
        "metricFilters": "",
        "dimensionsSort": [
         "originLevel1",
         "customEventType"
        ],
        "metricsHeaders": {},
        "bindOnLastSearch": true,
        "dimensionsHeaders": {},
        "editMode": false
       },
       {
        "id": "BEA1",
        "href": "",
        "title": "Events leveraging a third-party cookie",
        "sortBy": "PerformSearch",
        "filters": "(c_third_party_cookie_set==true)",
        "metrics": [
         "DocumentView",
         "CustomEvent",
         "PerformSearch"
        ],
        "cardType": "DetailedStatistics",
        "position": {
         "col": 3,
         "row": 7,
         "sizex": 2,
         "sizey": 4,
         "minSizex": 1,
         "minSizey": 2
        },
        "ascending": false,
        "showCount": false,
        "dimensions": [
         "customEventType",
         "originLevel1"
        ],
        "headerHref": "",
        "showHeader": true,
        "metricsSort": [
         "PerformSearch",
         "DocumentView",
         "CustomEvent"
        ],
        "metricFilters": "",
        "dimensionsSort": [
         "originLevel1",
         "customEventType"
        ],
        "metricsHeaders": {},
        "bindOnLastSearch": true,
        "dimensionsHeaders": {},
        "editMode": false
       },
       {
        "id": "2AB6",
        "href": "",
        "style": "info",
        "title": "Events sending Client ID",
        "value": "The table below needs to be identical to the \"All events\" table. If there are missing events, it means those events are not sending a Client ID, which is now required.\n",
        "cardType": "NoteCard",
        "position": {
         "col": 1,
         "row": 6,
         "sizex": 2,
         "sizey": 1,
         "minSizex": 1,
         "minSizey": 1
        },
        "eventType": "join",
        "headerHref": "",
        "isMarkdown": true,
        "editMode": false
       },
       {
        "id": "DBCE",
        "href": "",
        "style": "info",
        "title": "Events leveraging third-party cookie",
        "value": "The table below needs to be empty. If it's not empty, it means that a search hub is still leveraging a third-party cookie to set the Visitor ID.\n",
        "cardType": "NoteCard",
        "position": {
         "col": 3,
         "row": 6,
         "sizex": 2,
         "sizey": 1,
         "minSizex": 1,
         "minSizey": 1
        },
        "eventType": "join",
        "headerHref": "",
        "isMarkdown": true,
        "editMode": false
       },
       {
        "id": "A1D6",
        "href": "",
        "style": "info",
        "title": "All events",
        "value": "The event count in this table should always be the sum of the event counts from the two other tables in this dashboard.",
        "cardType": "NoteCard",
        "position": {
         "col": 1,
         "row": 1,
         "sizex": 4,
         "sizey": 1,
         "minSizex": 1,
         "minSizey": 1
        },
        "eventType": "join",
        "headerHref": "",
        "isMarkdown": true,
        "editMode": false
       }
      ],
      "editMode": false
     }
    ],
    "active": true,
    "editMode": false
   }
  ],
  "filters": "$",
  "version": 6
 },
 "allAnalyticsViewer": true,
 "filters": []
}

Was this article useful?

Very useful

Not really