Pushing Coveo Usage Analytics Page View Events

When you want to take advantage of Coveo Machine Learning recommendations, you need to push page view events from the website pages that you want to recommend (see Coveo Machine Learning Event Recommendations Deployment Overview and Coveo Machine Learning Recommendations Complete Code Sample).

You must adapt and add (typically to your page head section) a JavaScript code similar to the one in the following example to all the website pages that you want to track so they can be the object of recommendations.

Start pushing these events as soon as possible to build an history on which the recommendation model can learn.

The coveoua.js code also takes care of recording the session navigation history in the __coveo.analytics.history browser cookie. The content of the cookie is sent with the request in the actionsHistory parameter. Without this information, the recommendation model returns no suggestions.

<!-- Include the coveoua script from CDN to be able to log page view events -->
<script type="text/javascript" src="https://static.cloud.coveo.com/coveo.analytics.js/coveoua.js"></script>
<script>  
  // Replace by an API key with the *Execute query* and *Usage analytics write* privileges, 
  // or by a function that returns a valid search token.
  var accessToken = "*********-****-****-****-************";
  // Replace by the name of a field in your index whose values can uniquely identify each item.
  // You must be able to retrieve the value of that field for a given item using client-side code.
  var fieldName = "@clickableuri";
  // Replace by a function that allows you to consistently and accurately retrieve the value of the `fieldName` for each item.
  var fieldValue = location.href;
  // Replace by the item type to allow as recommendations. Use the empty string to allow recommendations of any type.
  var itemType = "Web Page";
  // Replace by any number of functions to retrieve custom contextual information.
  function getUserName() {
    // Implementation…
  };
  function getUserQuest() {
    // Implementation…
  };
  function getUserFavoriteColor() {
    // Implementation...
  };
  // ...
  coveoua("init", accessToken);
  coveoua("send", "pageview", {
    contentIdKey: fieldName,
    contentIdValue: fieldValue,
    contentType: itemType,
    // Optionally, to allow Coveo ML to take advantage of contextual information, you can pass any number of custom context key-value pairs.
    context_userName: getUserName(),
    context_userQuest: getUserQuest(),
    context_userFavoriteColor: getUserFavoriteColor() // ...
  });
</script>

Ensure to adapt the variables:

  • accessToken

    An appropriate Coveo Cloud API key or search token (see Get an API key).

    While the code pushing page view events can legitimately use an API key, when the search or website page in which you include the Recommendation component on the same page requires user authentication to be able to return secured results, you must use a search token that is generated for each user to initialize the component.

    A developer must set up a server-side mechanism to generate the search tokens using an API key that also carries the Search - Impersonate privilege (see Search Token Authentication).

  • fieldName

    Must contain the name of the Coveo index field used to uniquely identify the item (see Understanding Fields).

    The Recommendation service uses this field value to check with the index if the current user has the permissions to see each recommended item and returns only those that are allowed. When the field value does not match any indexed item, the recommendation is not returned.

    For a public website indexed with a Web source, the out-of-the-box @clickableuri field and the item URL proposed in the code sample generally do the job, the item URL being easily obtained with JavaScript.

    For items indexed in some types of sources, or for secured items in a regulated context (such as HIPAA) you may need to pick a field with hash values to prevent exposing any sensitive information. In such cases, you could use the @urihash or another unique ID field as long as you can get the hash value from the client-side.

    The @permanentid field is also a good choice (see About the PermanentId Field).

  • fieldValue

    Must contain the value found in the fieldName field for each item in the index. Sets the contentIdValue parameter of the coveoua function.

    When fieldName = '@clickableuri', the function in the sample typically correctly returns the item URI.

    When fieldName = '@urihash' or another hash value field such as @permanentid, you must change the function to get the hash value (from the Coveo index) so that it is the same value as the one in the index.

    You can inspect the Coveo index field values from the Content Browser to validate that the function returned value matches that of the Fields Tab. Ensure you use a pipeline that does not inject search results (like an Automatic Relevance Tuning model can do), and ensure that only one result is returned.

    With the @clickableuri field you would search for something like:

    @clickableuri="https://myWebsite.myCompany.com/This_is_some_document.html"

  • itemType

    Optionally, when you want to create recommendations for specific item types, indicate the type of item (see Coveo Machine Learning Recommendation Content Types). Sets the contentIdKey parameter of the coveoua function.

  • context_[key]

    Optionally, when you want recommendations to be context sensitive, add one or more custom context key/value pairs that you planned (see Leveraging Custom Contexts in Coveo Machine Learning Features).

    Your custom context key name must start with the context_ prefix to ensure that their values are automatically taken into account by Coveo ML models.

    In your search interface, the users are authenticated and you wrote a getUserRole function to return the user role (End-user, Administrator, or Developer) from the profile of the current user performing the query. Your custom context key is userRole, so the line would be:

      context_userRole: getUserRole();
    

The script source comes from the GitHub coveo.analytics.js project.

Tracking the Current User

The first pageview sent by the browser triggers in Coveo Usage Analytics the creation of a temporary unique identifier that is bound to the current user. Subsequent calls to pageview will send this identifier along with the data, which will be used to track the current user’s history.

What’s Next?

You probably want to add a Recommendation component in some of your website pages to show recommended content. You must start by adding the JavaScript Search Framework resources to your pages (see Including Coveo JavaScript Search Framework in a Page with Recommendations).