Leverage the Coveo UA library
Leverage the Coveo UA library
This is for:
DeveloperYou can use Headless controllers to handle Search API requests and leverage Coveo Usage Analytics (Coveo UA). Headless-powered search UI components can automatically log search and click events for user interactions in your search interfaces. These events provide the data to power most Coveo Machine Learning (Coveo ML) models, except for Content Recommendations (CR).
The output of a CR model depends on view events and the user’s action history. Headless doesn’t log these events for you, so you should ensure that you’re sending view events for each page that you want to be able to recommend.
Leading practice
Start sending view events as soon as you can to gather data that your CR models can learn from. |
Send view events
Use the Coveo UA library to send view events 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>",
customData: {
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 |
|||
The send command returns a promise.
To send mutliple events sequentially, use await :
Example
|
|||
<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 UA library is also available as an npm package. You can install it with the following command:
npm i coveo.analytics
You’ll want to have a module bundler (such as webpack) installed and configured.
The following code sample references the Coveo UA library as an ESM module and sends a view event when a web page is loaded.
import { CoveoAnalyticsClient } from 'coveo.analytics/modules';
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 site, 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. |