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.

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

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>">
  <!-- Set `title` metadata for view events sent from this page. -->
  <!-- Import script to send view events and record actions history. -->
  <script type="text/javascript"
    // Send view events.
    coveoua("init", "<ACCESS_TOKEN>");
    coveoua("send", "pageview", {
      contentIdKey: "<FIELD_NAME>",
      contentIdValue: "<FIELD_VALUE>",
      contentType: "<CONTENT_TYPE>",
      // ... Additional custom context information ...
  <!-- ... -->
<!-- ... -->

Ensure to replace the following placeholder values:


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


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


    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 Choose and Implement a Search Authentication Method.


    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.


    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.


    (Optional) The type of content being tracked.


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

What's Next for Me?