Send Usage Analytics View Events

The output of a Coveo Machine Learning (Coveo ML) Event Recommendations (ER) model depends heavily on view usage analytics events and user actions history. Therefore, you should ensure that each page you want to be able to recommend is recording the required data.

To do so, 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.

Start sending view event events as soon as you can to gather data on which your Event 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/coveoua.js">
  </script>
  <script>
    // Send view events.
    coveoua("init", "<ACCESS_TOKEN>");
    coveoua("send", "pageview", {
      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.

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

    See also Choosing and Implementing a Search Authentication Method.

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

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

Understanding How Coveo Usage Analytics (Coveo UA) Tracks Users and Sessions

The first usage analytics event sent from a browser triggers the creation of a unique visitorId, which is stored in a non-expiring browser cookie. Subsequent calls to the Usage Analytics Write API include this cookie, allowing the current user (i.e., browser) to be tracked.

Coveo UA also automatically tracks user sessions by associating each active visitorId to a temporary visitId, which expire after 30 minutes of user idleness.

What’s Next?

You’re now ready to add a recommendation interface to web pages to show recommended content.

Recommended Articles