JavaScript Search Framework Usage Analytics

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

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

Administrators can leverage recorded UA data to evaluate how end users are interacting with a search interface, identify content gaps, and improve relevancy by generating and examining dashboards and reports within the 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 is enforced in the search token or API key. Otherwise, all UA Write API requests from that search interface will fail with 400 errors (i.e., 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>

In a standalone search interface that doesn’t include an Analytics component (e.g., 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 end-user interactions in your search interface.

The JavaScript Search Framework exposes top level functions that let you log three different types of 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 : "" }; (1)
const metadata = { key1: "value 1", key2: "value 2" }; (2)
Coveo.logSearchEvent(root, cause, metadata);
Coveo.executeQuery(root); (3)
1 The cause object must implement the IAnalyticsActionCause interface. However, specifying a type other than the empty string ("") is only useful when sending Custom events.
2 The metadata object must be a map of strings or an empty object ({}).
3 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 : "" }; (1)
const metadata = { key1: "value 1", key2: "value 2" }; (2)
const result = getOpenedResult(); (3)
Coveo.logClickEvent(root, cause, metadata, result);
1 The cause object must implement the IAnalyticsActionCause interface. However, specifying a type other than the empty string ("") is only useful when sending Custom events.
2 The metadata object must be a map of strings or the empty object ({}).
3 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 end-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" }; (1)
const metadata = { key1: "value 1", key2: "value 2" }; (2)
Coveo.logCustomEvent(root, cause, metadata);
1 The cause object must implement the IAnalyticsActionCause interface. The type value can be used to group similar Custom events in UA reports.
2 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 (e.g., "Admin", "Developer").
}
 
const root = document.getElementById("search");
root.addEventListener("changeAnalyticsCustomData", (args) => {
  if (args.detail.type === "SearchEvent") { (1)
    args.detail.metaObject["userRole"] = getUserRole(); (2)
  }
});
 
// ...
 
Coveo.init(root); (3)
1 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.
2 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.
3 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 in order to ensure that they can’t be clearly 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. When implementing a cookie policy, you may need to disable UA tracking for end-users under specific circumstances (e.g., when a user decides to disable functionality cookies).

To do so, you can call the disable method on the Analytics component. Calling this method will also clear all Coveo UA-related information stored in the browser (coveo_visitorId cookie, action history, etc.)

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.

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.

What's Next for Me?