Usage analytics

This is for:

Developer

In this article

Set the search hub
Send your own UA events
Modify the metadata to send with UA events
Anonymize UA data
Disable and enable analytics
What’s next?

The Analytics component is responsible for automatically sending HTTP requests to the Coveo Usage Analytics (Coveo UA) Write API to record events that represent standard user interactions with a search interface. In addition, including this component in your search interface lets you send your own UA events.

<div id="search" class="CoveoSearchInterface">
  <div class="CoveoAnalytics"></div>
  <!-- ... -->
</div>

Administrators can leverage recorded UA data to evaluate how users are interacting with a search interface, identify content gaps, and improve relevancy by generating and examining dashboards and reports within the Coveo Administration Console (see Coveo Usage Analytics overview). Moreover, Coveo Machine Learning (Coveo ML) features require UA data to function.

Set the search hub

The search hub (or origin level 1) identifies the search interface from which Search API and UA Write API requests are being sent. This information is vital for query pipeline routing, UA reporting, and enabling Coveo ML features in an implementation.

Depending on which authentication method you’re using in your search interface, you will normally enforce the search hub in the search token or in the API key.

In addition, when your search interface includes an Analytics component, you must set its searchHub option to the same search hub value that’s enforced in the search token or API key. Otherwise, all UA Write API requests from that search interface will fail with 400 errors (that is, no UA events will be logged for that interface).

For example, if you’re using API key authentication in a search interface, and your API key is enforcing the Community search hub as a constraint, you must configure the Analytics component as follows:

<div id="search" class="CoveoSearchInterface">
  <div class="CoveoAnalytics"
       data-search-hub="Community">
  </div>
  <!-- ... -->
</div>

Note

In a standalone search interface that doesn’t include an Analytics component (for example, global search box), enforcing the search hub in the search token or API key is sufficient.

Send your own UA events

In addition to the standard UA events that are automatically logged by the Analytics component, you may want to send your own UA events to track specific user interactions in your search interface.

The Coveo JavaScript Search Framework exposes top level functions that let you log three different types of events:

Search events
Click events
Custom events

Regardless of its type, a UA event always requires a cause (an object) and some metadata (a map of strings, or an empty object).

Send search events

Search events are intended to record end-user interactions that trigger queries, such as:

Submitting a search request from the search box
Selecting a facet value

Depending on your use case, use the logSearchEvent or the logSearchAsYouTypeEvent top-level function to send your own search events.

const root = document.getElementById("search");
const cause = { name : "mySearchEventName", type : "" }; 
const metadata = { key1: "value 1", key2: "value 2" }; 
Coveo.logSearchEvent(root, cause, metadata);
Coveo.executeQuery(root);

	The cause object must implement the `IAnalyticsActionCause` interface. However, specifying a `type` other than the empty string (`""`) is only useful when sending custom events.
	The metadata object must be a map of strings or an empty object (`{}`).
	You must execute a query to log the search event.

Send click events

Click events are intended to record item view and preview actions, such as:

Opening a result link
Opening a result Quick view

Use the logClickEvent top level function to send your own click events.

function getOpenedResult() {
  // Implementation; returns the opened IQueryResult.
}
const root = document.getElementById("search");
const cause = { name : "myCustomClickEventName", type : "" }; 
const metadata = { key1: "value 1", key2: "value 2" }; 
const result = getOpenedResult(); 
Coveo.logClickEvent(root, cause, metadata, result);

	The cause object must implement the `IAnalyticsActionCause` interface. However, specifying a `type` other than the empty string (`""`) is only useful when sending custom events.
	The metadata object must be a map of strings or the empty object (`{}`).
	When calling the `logClickEvent` function, the last argument must be a reference to the opened or previewed `IQueryResult`.

Send custom events

Custom events are intended to record user interactions that don’t trigger a query or open a query result, such as:

Updating end-user preferences
Changing the result list layout

const root = document.getElementById("search");
const cause = { name: "myCustomEventName", type: "myCustomEventType" }; 
const metadata = { key1: "value 1", key2: "value 2" }; 
Coveo.logCustomEvent(root, cause, metadata);

	The cause object must implement the `IAnalyticsActionCause` interface. The `type` value can be used to group similar custom events in UA reports.
	The metadata object must be a map of strings or an empty object (`{}`).

Modify the metadata to send with UA events

It can be useful to add or modify metadata to send along with the standard UA events logged by the Analytics component. You can do so by attaching a handler on the changeAnalyticsCustomData event.

function getUserRole() {
  // Implementation; returns a string (for example, "Admin", "Developer").
}
 
const root = document.getElementById("search");
root.addEventListener("changeAnalyticsCustomData", (args) => {
  if (args.detail.type === "SearchEvent") { 
    args.detail.metaObject["userRole"] = getUserRole(); 
  }
});
 
// ...
 
Coveo.init(root);

	All `changeAnalyticsCustomData` event handlers receive an `IChangeAnalyticsCustomDataEventArgs` object as an argument. In this example, we read the `type` property of this object to only modify search events.
	Some properties of the `IChangeAnalyticsCustomDataEventArgs` object, such as `metaObject`, can be modified. In this example, we add (or modify) the arbitrary `userRole` key-value pair in the event’s metadata object.
	You should always register event handlers before the `init` call of your search interface.

Anonymize UA data

If the users of your search interface are authenticated, you may want to hash their identities to ensure that they can’t be identified in UA data.

To do so, set the anonymous option to true on the Analytics component.

<div id="search" class="CoveoSearchInterface">
  <div class="CoveoAnalytics"
       data-anonymous="true">
  </div>
  <!-- ... -->
</div>

Disable and enable analytics

Coveo UA uses the coveo_visitorId cookie to track individual users and sessions. Although the visitorId query parameter has been deprecated, the cookie’s name has not been changed to ensure compatibility.

When implementing a cookie policy, you may need to disable UA tracking for end users under specific circumstances (for example, when a user opts out of cookies). To do so, you can call the disable method on the Analytics component.

To re-enable UA tracking, call the enable method.

let analytics = document.querySelector(".CoveoAnalytics");
analytics = Coveo.get(analytics);
analytics.disable();
// Or analytics.enable();

Coveo ML features require UA data to function. Therefore, disabling UA tracking for many users can have disastrous consequences on the relevance of a search interface.

To clear local session information from the browser without disabling analytics completely, use the clearLocalData function.

If you want to disable usage analytics completely in a JavaScript Search Framework interface, the simplest way to do so is to not initialize an Analytics component at all.

What’s next?

You may want to use the Analytics component along with a data layer object and Google Tag Manager to log search page UA data to Google Analytics.