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 uniquename
. A custom usage analytics event action cause may also have a broadertype
, 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, thetype
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 useF00 b4r
as a metadata key, the service transforms it toc_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).