Send Usage Analytics View Events

The output of a Coveo Machine Learning (Coveo ML) Content Recommendations (CR) model depends heavily on the view events and user actions history. Therefore, you should ensure that each page you want to be able to recommend has a page view tracker to record the required data.

Note

If you are using a Coveo ML Content Recommendations (CR) model that leverages collect events to render product recommendations, see Send Page Views Events When Using Collect Events for instructions.

To implement a page view tracker, you’re encouraged to use the open source coveoua.js script (See coveo.analytics.js). Once properly configured, this script automatically takes care of sending view events and recording user actions history accordingly.

Tip
Leading practice

Start sending view events as soon as you can to gather data on which your Content Recommendations models can learn.

You can use code similar to what follows 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>");
    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>

Ensure to replace the following placeholder values:

  • <PAGE_LANGUAGE>

    The language identifier of the tracked page. The coveoua.js script uses this value to populate the language metadata when sending view events.

    Important

    Since Coveo ML models are split into distinct submodels for each language, you should ensure that the lang HTML attribute is correctly set in each page you’re tracking using the coveoua.js script (see What Languages Do Coveo ML Models Support?).

  • PAGE_TITLE

    The title of the tracked page. The coveoua.js script uses this value to populate the title metadata when sending view events.

  • <ACCESS_TOKEN>

    A public API key granted only the privileges to execute queries and to push usage analytics data in the target Coveo organization, or a valid search token if the page requires user authentication (see Search Token Authentication, and Execute Queries Domain and Analytics Data Domain).

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

    For pages in a public website, the @clickableuri field is generally a good choice, as you can easily obtain a web page 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 to allow further recommendation personalization (see About Custom Context).

    When using the coveoua.js script to log view events, all user context key names must be prefixed with context_.

    Example

    In your search interface, the users are authenticated and you wrote a getUserRole function to return the user role (customer, employee, or partner) from the profile of the current user performing the query. Your custom context key is userRole, so you would pass it as follows when logging a view event with the coveoua.js script:

    context_userRole: getUserRole();

    If you’re passing user context key-values along with view events, you will likely want to ensure that your recommendation interface does so as well when it sends queries (see Leveraging User Context Data in a Recommendation Interface).

Send Page Views Events When Using Collect Events

When using a Coveo ML Content Recommendations (CR) model that leverages collect events to render product recommendations, you must ensure that pageview events sent to Coveo UA contain a contentIdKey and contentIdValue defined as custom fields. The following code sample shows the coveo.analytics.js script in which a 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’s contentIdKey (e.g., @permanentId).

  • <MY_CONTENTIDVALUE> is the value of the item’s contentIdValue.

  • <COVEO_API_KEY> is the API key created for your catalog (see API Key for Analytics).

  • <COVEO_UA_ENDPOINT> is the Coveo UA Endpoint, if necessary.

To understand how Coveo Usage Analytics tracks users and sessions, see Client ID, Visitor ID, and Visit ID Dimensions.