Leverage the analytics library

This is for:

Developer

In this article

Send view events

You can use Headless controllers to handle Search API requests and leverage Coveo Usage Analytics (Coveo UA). Headless-powered search UI components can automatically log search and click events for user interactions in your search interfaces. These events provide the data to power most Coveo Machine Learning (Coveo ML) models, except for Content Recommendations (CR).

The output of a CR model depends on view events and the user’s action history. Headless doesn’t log these events for you, so you should ensure that you’re sending view events for each page that you want to be able to recommend.

Leading practice

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

Send view events

Use the Coveo UA library to send view events 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>"> 
<head>
  <!-- Set `title` metadata for view events sent from this page. -->
  <title>PAGE_TITLE</title> 
  <!-- 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>"); 
    coveoua("send", "view", { 
      contentIdKey: "<FIELD_NAME>", 
      contentIdValue: "<FIELD_VALUE>", 
      contentType: "<CONTENT_TYPE>", 
      customData: {
        context_CONTEXT_KEY: "<CUSTOM_CONTEXT_VALUE>" 
        // ... Additional custom context information ...
      }
    });
  </script>
  <!-- ... -->
</head>
<!-- ... -->
</html>

<PAGE_LANGUAGE>: The language identifier of the tracked page. Coveo UA uses this value to populate the language metadata when sending view events.

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.

PAGE_TITLE: The title of the tracked page. Coveo UA uses this value to populate the title metadata when sending view events.

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

The send command returns a promise. To send mutliple events sequentially, use await:

Example

async function sendEvents() {
  try {
    await coveoua("send", "view", { /* event data */ });
    await coveoua("send", "view", { /* event data */ });
  } catch (error) {
    console.error("Error sending events:", error);
  }
}

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

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

<CONTENT_TYPE>: (Optional) The type of content being tracked.

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 UA library is also available as an npm package. You can install it with the following command:

npm i coveo.analytics

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

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

import { CoveoAnalyticsClient } from 'coveo.analytics/modules';
const ua = new CoveoAnalyticsClient({token: '<ACCESS_TOKEN>', endpoint: '<ANALYTICS_ENDPOINT>'}); 
ua.sendViewEvent({
  contentIdKey: '<FIELD_NAME>', 
  contentIdValue: '<FIELD_VALUE>', 
  contentType: '<CONTENT_TYPE>' 
});

	`<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.
	`<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 site, because you can retrieve a web page’s URL using JavaScript code.
	`<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.
	`<CONTENT_TYPE>`: (Optional) The type of content being tracked.