Send Your Own Search, Click, or Custom Events

In addition to the standard usage analytics events automatically logged by the Coveo™ JavaScript Search Framework when an Analytics component is present in your search interface, you may want to log custom usage analytics events. This article explains how to interact with the Usage Analytics Write API through top-level JavaScript Search Framework functions, so you don’t have to call the service directly.

Defining a Usage Analytics Event

The JavaScript Search Framework allows you to send three types of usage analytics events:

• Search (see Logging Your Own Search Events)

  Records end-user actions that trigger queries, such as:

  • Submitting a search request from the search box

  • Selecting a facet value

• Click (see Logging Your Own Click Events)

  Records query result item view and preview actions, such as:

  • Clicking a result link

  • Clicking the quick view icon

• Custom (see Logging Your Own Custom Events)

  Records end-user actions that are neither search nor click events, such as:

  • Updating end-user preferences

  • Changing the result list layout

Regardless of its type, a usage analytics event must have:

• An action cause, which provides a generic description of the usage analytics event. An action cause must minimally have a unique name. A custom usage analytics event action cause may also have a broader type, which can be used to group similar custom events.

  Specifying a usage analytics event action cause type is only meaningful when logging custom events. When logging click or search events, the type attribute is entirely ignored.

• Metadata, which is a JSON object whose key-value pairs provide additional contextual information about the usage analytics event. If you don’t want to include metadata when logging a usage analytics event, you can pass an empty JSON object ({}).

  Each metadata key must match the [A-Za-z0-9_ ]* regular expression, and each value must be a simple string or an array of strings. You can’t use other primitive types (Boolean, number, etc.), or objects as metadata values.

  The Usage Analytics Write API further formats each metadata key to make it match the c_[a-z0-9_]* regular expression. This means that if you use F00 b4r as a metadata key, the service transforms it to c_f00_b4r.

  You will typically want to create user-defined dimensions to be able to leverage your custom event metadata in usage analytics reports and dashboards (see Manage Dimensions on Custom Metadata).

let myEventActionCause = {
  name: 'clearWithEscape',
  type: 'searchbox'
};
 
let myEventMetadata = {
  cleared_query_expression: 'coveo machine learning'
};

Logging Your Own Search Events

Use the logSearchEvent top-level function to log search events. If it suits the action you want to record better, you can use the logSearchAsYouTypeEvent top-level function instead.

let element = Coveo.$$(document).find('#search');
// Specifying a type is only useful when logging Custom usage analytics events.
let searchEventCause = { name : 'mySearchEventName', type : '' };
let metadata = { key_1: 'value 1', key_2: ['value 2.1', 'value 2.2'], key_n: 'value n' };
Coveo.logSearchEvent(element, searchEventCause, metadata);
// You must execute to log the Search event.
Coveo.executeQuery(document.body);

Logging Your Own Click Events

Use the logClickEvent top-level function to log click events.

let element = Coveo.$$(document).find('#search');
// Specifying a type is only useful when logging Custom usage analytics events.
let clickEventCause = { name : 'myCustomClickEventName', type : '' };
let metadata = { key_1: 'value 1', key_2: ['value 2.1', 'value 2.2'], key_n: 'value n' };
Coveo.logClickEvent(element, clickEventCause, metadata, result);

Logging Your Own Custom Events

Use the logCustomEvent top-level function to log custom events.

let element = Coveo.$$(document).find('#search');
// Specifying a type is only useful when logging Custom usage analytics events.
let customEventCause = { name: 'myCustomEventName', type: 'myCustomEventType' };
let metadata = { key_1: 'value 1', key_2: ['value 2.1', 'value 2.2'], key_n: 'value n' };
Coveo.logCustomEvent(element, customEventCause, metadata);

Code Sample

<!-- ... -->
 
<button id='cancelHelpRequestButton'>
  <script>
    function cancelHelpRequestButtonWasClicked() {
      let element = Coveo.$$(document).find('#search');
      let customEventCause = { name: 'cancelHelpRequest', type: 'caseDeflection' };
      let metadata = {
        product_name: getCaseProductName(),
        product_version: getCaseProductVersion(),
        displayedResults: getDisplayedResultIds()
      };
      Coveo.logCustomEvent(element, customEventCause, metadata);
    }
    Coveo.$$(Coveo.$$(document).find('#cancelHelpRequestButton')).on('click', cancelHelpRequestButtonWasClicked);
  </script>
</button>
 
<!-- ... -->
 
<div id='search' class='CoveoSearchInterface'>
 
<!-- ... -->
 
  <div class='CoveoAnalytics'></div>
 
<!-- ... -->

  <div class="CoveoAnalytics" data-endpoint="https://analyticshipaa.cloud.coveo.com/rest/ua"></div>

What’s Next?

Rather than sending your own usage analytics events, it’s also possible to merely modify the standard ones sent by the Analytics component (see Send Custom Metadata with Search, Click, or Custom Events).