Leverage the Coveo analytics library
Leverage the Coveo analytics library
Coveo Usage Analytics (Coveo UA) lets you track user interactions with your search interfaces so that you can optimize your Coveo solution. Search, click, and custom events provide the data to power most Coveo Machine Learning (Coveo ML) models, with the exception of Content Recommendations (CR).
The output of a CR model depends on view events and the user’s action history. The Coveo search UI libraries (Atomic, Headless, and the JavaScript Search Framework) don’t log these events for you, so you should ensure that you’re sending page view events for each page that you want to be able to recommend.
If you’re using a CR model that leverages collect events to render content recommendations, see Send page view events when using collect events for instructions.
|
Leading practice
Start sending view events as soon as you can to gather data that your CR models can learn from. |
Send page view events
Use the Coveo analytics library to send page views to Coveo UA. You can load it from a CDN link or install it as an NPM package.
CDN
The following code sample leverages the open source coveoua.js
script to send a view event when a web page is loaded.
<!DOCTYPE html>
<!-- Set `language` metadata for view events sent from this page. -->
<html lang="<PAGE_LANGUAGE>">
<head>
<!-- Set `title` metadata for view events sent from this page. -->
<title>PAGE_TITLE</title>
<!-- Import script to send view events and record actions history. -->
<script type="text/javascript"
src="https://static.cloud.coveo.com/coveo.analytics.js/2/coveoua.js">
</script>
<script>
// Send view events.
coveoua("init", "<ACCESS_TOKEN>", "<ANALYTICS_ENDPOINT>");
coveoua("send", "view", {
contentIdKey: "<FIELD_NAME>",
contentIdValue: "<FIELD_VALUE>",
contentType: "<CONTENT_TYPE>",
context_CONTEXT_KEY: "<CUSTOM_CONTEXT_VALUE>"
// ... Additional custom context information ...
});
</script>
<!-- ... -->
</head>
<!-- ... -->
</html>
<PAGE_LANGUAGE> : The language identifier of the tracked page.
Coveo UA uses this value to populate the language metadata when sending view events.
|
|||
PAGE_TITLE : The title of the tracked page.
Coveo UA uses this value to populate the title metadata when sending view events. |
|||
<ACCESS_TOKEN> : A public API key that’s only granted the privileges to execute queries and push UA data in the target Coveo organization, or a valid search token if the page requires user authentication (see Choose and implement a search authentication method, Search token authentication, Execute queries domain, and Analytics data domain).
Where |
|||
<FIELD_NAME> : The name of a field that can be used to uniquely and permanently identify the tracked page as an item in the index (see About fields).
The @clickableuri field is a good choice for pages in a public website, because you can retrieve a web page’s URL using JavaScript code. |
|||
<FIELD_VALUE> : The value of the <FIELD_NAME> field for the current tracked page.
If <FIELD_NAME> is set to @clickableuri , the window.location.href JavaScript function typically returns the matching <FIELD_VALUE> for the current page. |
|||
<CONTENT_TYPE> : (Optional) The type of content being tracked. |
|||
CONTEXT_KEY /<CUSTOM_CONTEXT_VALUE> : (Optional) The user context key-value pairs to pass for more personalized recommendations.
When you log view events with Coveo UA, all user context key names must be prefixed with context_ .
Example
In your search interface, the users are authenticated and you wrote a
|
NPM
The Coveo analytics library is also available as an npm package. You can install it with the following command:
npm i coveo.analytics
You will want to have a module bundler (such as webpack) installed and configured.
The following code sample references the Coveo analytics library as an ESM module and sends a view event when a web page is loaded.
import { CoveoAnalyticsClient } from 'coveo.analytics';
const ua = new CoveoAnalyticsClient({token: '<ACCESS_TOKEN>', endpoint: '<ANALYTICS_ENDPOINT>'});
ua.sendViewEvent({
contentIdKey: '<FIELD_NAME>',
contentIdValue: '<FIELD_VALUE>',
contentType: '<CONTENT_TYPE>'
});
<ACCESS_TOKEN> : A public API key that’s only granted the privileges to execute queries and push UA data in the target Coveo organization, or a valid search token if the page requires user authentication (see Choose and implement a search authentication method, Search token authentication, Execute queries domain, and Analytics data domain).
Where |
|
<FIELD_NAME> : The name of a field that can be used to uniquely and permanently identify the tracked page as an item in the index (see About fields).
The @clickableuri field is a good choice for pages in a public website, because you can retrieve a web page’s URL using JavaScript code. |
|
<FIELD_VALUE> : The value of the <FIELD_NAME> field for the current tracked page.
If <FIELD_NAME> is set to @clickableuri , the window.location.href JavaScript function typically returns the matching <FIELD_VALUE> for the current page. |
|
<CONTENT_TYPE> : (Optional) The type of content being tracked. |
Send page view events when using collect events
You can use a
CR model
which leverages collect events to render content recommendations.
In this case, all of the pageview
events that are sent to
Coveo UA
must contain a contentIdKey
and contentIdValue
, both of which are defined as custom
fields.
The following code sample shows a coveoua.js
script in which contentIdKey
and contentIdValue
are added as custom
fields:
<script>
(function(c,o,v,e,O,u,a){
a='coveoua';c[a]=c[a]||function(){(c[a].q=c[a].q|| []).push(arguments)};
c[a].t=Date.now();u=o.createElement(v);u.async=1;u.src=e;
O=o.getElementsByTagName(v)[0];O.parentNode.insertBefore(u,O)
})(window,document,'script','https://static.cloud.coveo.com/coveo.analytics.js/2/coveoua.js')
coveoua('set', 'custom', {
contentIdKey: '<MY_CONTENTIDKEY>',
contentIdValue: '<MY_CONTENTIDVALUE>'
});
coveoua('init', '<COVEO_API_KEY>', '<COVEO_UA_ENDPOINT>');
coveoua('send', 'pageview');
</script>
Where:
-
<MY_CONTENTIDKEY>
is the value of the item’scontentIdKey
(for example,@permanentid
). -
<MY_CONTENTIDVALUE>
is the value of the item’scontentIdValue
(for example,648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960
). -
<COVEO_API_KEY>
is the API key created for your catalog. -
<COVEO_UA_ENDPOINT>
is the Coveo UA endpoint.
|
Note
To understand how Coveo UA tracks users and sessions, see What’s a user visit?. |