Leverage the Coveo analytics library

This is for:

Developer

Coveo Usage Analytics (Coveo UA) lets you track user interactions with your search interfaces so that you can optimize your Coveo solution. Search, click, and custom events provide the data to power most Coveo Machine Learning (Coveo ML) models, with the exception of Content Recommendations (CR).

The output of a CR model depends on view events and the user’s action history. The Coveo search UI libraries (Atomic, Headless, and the JavaScript Search Framework) don’t log these events for you, so you should ensure that you’re sending page view events for each page that you want to be able to recommend.

If you’re using a CR model that leverages collect events to render content recommendations, see Send page view events when using collect events for instructions.

Tip
Leading practice

Start sending view events as soon as you can to gather data that your CR models can learn from.

Send page view events

Use the Coveo analytics library to send page views to Coveo UA. You can load it from a CDN link or install it as an NPM package.

CDN

The following code sample leverages the open source coveoua.js script to send a view event when a web page is loaded.

<!DOCTYPE html>
<!-- Set `language` metadata for view events sent from this page. -->
<html lang="<PAGE_LANGUAGE>"> 1
<head>
  <!-- Set `title` metadata for view events sent from this page. -->
  <title>PAGE_TITLE</title> 2
  <!-- Import script to send view events and record actions history. -->
  <script type="text/javascript"
          src="https://static.cloud.coveo.com/coveo.analytics.js/2/coveoua.js">
  </script>
  <script>
    // Send view events.
    coveoua("init", "<ACCESS_TOKEN>", "<ANALYTICS_ENDPOINT>"); 3
    coveoua("send", "view", {
      contentIdKey: "<FIELD_NAME>", 4
      contentIdValue: "<FIELD_VALUE>", 5
      contentType: "<CONTENT_TYPE>", 6
      context_CONTEXT_KEY: "<CUSTOM_CONTEXT_VALUE>" 7
      // ... Additional custom context information ...
    });
  </script>
  <!-- ... -->
</head>
<!-- ... -->
</html>
1 <PAGE_LANGUAGE>: The language identifier of the tracked page. Coveo UA uses this value to populate the language metadata when sending view events.
Important

Coveo ML models are split into distinct submodels for each language, so you should set the lang HTML attribute for each page that you’re tracking.
2 PAGE_TITLE: The title of the tracked page. Coveo UA uses this value to populate the title metadata when sending view events.
3 <ACCESS_TOKEN>: A public API key that’s only granted the privileges to execute queries and push UA data in the target Coveo organization, or a valid search token if the page requires user authentication (see Choose and implement a search authentication method, Search token authentication, Execute queries domain, and Analytics data domain).

<ANALYTICS_ENDPOINT>: Your organization analytics endpoint.

  • https://<ORG_ID>.analytics.org.coveo.com for a non-HIPAA organization

  • https://<ORG_ID>.analytics.orghipaa.coveo.com for a HIPAA organization

Where <ORG_ID> is the unique identifier of your Coveo organization.
4 <FIELD_NAME>: The name of a field that can be used to uniquely and permanently identify the tracked page as an item in the index (see About fields). The @clickableuri field is a good choice for pages in a public website, because you can retrieve a web page’s URL using JavaScript code.
5 <FIELD_VALUE>: The value of the <FIELD_NAME> field for the current tracked page. If <FIELD_NAME> is set to @clickableuri, the window.location.href JavaScript function typically returns the matching <FIELD_VALUE> for the current page.
6 <CONTENT_TYPE>: (Optional) The type of content being tracked.
7 CONTEXT_KEY/<CUSTOM_CONTEXT_VALUE>: (Optional) The user context key-value pairs to pass for more personalized recommendations. When you log view events with Coveo UA, all user context key names must be prefixed with context_.
Example

In your search interface, the users are authenticated and you wrote a getUserRole function to return the user role (customer, employee, or partner) from the profile of the current user performing the query. Your custom context key is userRole, so you would pass it as follows when logging a view event:

context_userRole: getUserRole();
Note

If you’re passing user context key-values along with view events, you will likely want to ensure that your recommendation interface does so as well when it sends queries.

NPM

The Coveo analytics library is also available as an npm package. You can install it with the following command:

npm i coveo.analytics

You will want to have a module bundler (such as webpack) installed and configured.

The following code sample references the Coveo analytics library as an ESM module and sends a view event when a web page is loaded.

import { CoveoAnalyticsClient } from 'coveo.analytics';
const ua = new CoveoAnalyticsClient({token: '<ACCESS_TOKEN>', endpoint: '<ANALYTICS_ENDPOINT>'}); 1
ua.sendViewEvent({
  contentIdKey: '<FIELD_NAME>', 2
  contentIdValue: '<FIELD_VALUE>', 3
  contentType: '<CONTENT_TYPE>' 4
});
1 <ACCESS_TOKEN>: A public API key that’s only granted the privileges to execute queries and push UA data in the target Coveo organization, or a valid search token if the page requires user authentication (see Choose and implement a search authentication method, Search token authentication, Execute queries domain, and Analytics data domain).

<ANALYTICS_ENDPOINT>: Your organization analytics endpoint.

  • https://<ORG_ID>.analytics.org.coveo.com for a non-HIPAA organization

  • https://<ORG_ID>.analytics.orghipaa.coveo.com for a HIPAA organization

Where <ORG_ID> is the unique identifier of your Coveo organization.
2 <FIELD_NAME>: The name of a field that can be used to uniquely and permanently identify the tracked page as an item in the index (see About fields). The @clickableuri field is a good choice for pages in a public website, because you can retrieve a web page’s URL using JavaScript code.
3 <FIELD_VALUE>: The value of the <FIELD_NAME> field for the current tracked page. If <FIELD_NAME> is set to @clickableuri, the window.location.href JavaScript function typically returns the matching <FIELD_VALUE> for the current page.
4 <CONTENT_TYPE>: (Optional) The type of content being tracked.

Send page view events when using collect events

You can use a CR model which leverages collect events to render content recommendations. In this case, all of the pageview events that are sent to Coveo UA must contain a contentIdKey and contentIdValue, both of which are defined as custom fields.

The following code sample shows a coveoua.js script in which contentIdKey and contentIdValue are added as custom fields:

<script>
  (function(c,o,v,e,O,u,a){
  a='coveoua';c[a]=c[a]||function(){(c[a].q=c[a].q|| []).push(arguments)};
  c[a].t=Date.now();u=o.createElement(v);u.async=1;u.src=e;
  O=o.getElementsByTagName(v)[0];O.parentNode.insertBefore(u,O)
  })(window,document,'script','https://static.cloud.coveo.com/coveo.analytics.js/2/coveoua.js')

  coveoua('set', 'custom', {
    contentIdKey: '<MY_CONTENTIDKEY>',
    contentIdValue: '<MY_CONTENTIDVALUE>'
  });
  coveoua('init', '<COVEO_API_KEY>', '<COVEO_UA_ENDPOINT>');
  coveoua('send', 'pageview');
</script>

Where:

  • <MY_CONTENTIDKEY> is the value of the item’s contentIdKey (for example, @permanentid).

  • <MY_CONTENTIDVALUE> is the value of the item’s contentIdValue (for example, 648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960).

  • <COVEO_API_KEY> is the API key created for your catalog.

  • <COVEO_UA_ENDPOINT> is the Coveo UA endpoint.

Note

To understand how Coveo UA tracks users and sessions, see What’s a user visit?.