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:

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

The following script defines two variables which would likely be used to log a custom usage analytics event, since an action cause type is specified.

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.

You must execute a query after calling the logSearchEvent or logSearchAsYouTypeEvent function. Otherwise, no event will be sent to the service.

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.

The last argument of the logClickEvent function must be a reference to the opened or previewed IQueryResult.

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.

When logging a Custom usage analytics event, consider specifying a value for the type property of the second argument (customEventCause) as this will allow you to group similar Custom events in usage analytics dashboards and reports.

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

The following example shows how you could bind a click event handler to a Cancel Help Request button to log a Custom case deflection event through the Usage Analytics Write API.

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

If your Coveo organization is in the HIPAA environment, set the endpoint option of your Analytics component to https://usageanalyticshipaa.cloud.coveo.com.

To do so, replace <div class='CoveoAnalytics'></div> in the above code sample by:

  <div class="CoveoAnalytics" data-endpoint="https://usageanalyticshipaa.cloud.coveo.com"></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).

Recommended Articles