Pushing View Events to Coveo Usage Analytics

The number of views of a particular item is an insightful indication of its relevance. It helps Coveo Machine Learning to identify the current user’s area of interests and ultimately improves the accuracy of the Automatic Relevance Tuning (ART) model for all other users.

As a part of the Deploying Coveo for Microsoft Dynamics 365 in a Portal series, this page helps you register a user visit to a portal page by pushing a view event to Coveo Usage Analytics (Coveo UA). For more general information on view events, see Pushing Coveo Usage Analytics View Events.

Before you start, ensure that Coveo/ApiKey is set with a valid API key and that coveoua.js is loaded in the page (see Adding a Web Template for Coveo Scripts and Stylesheets).

Adding a Web Template to Push View Events to Coveo UA

In Dynamics, create a new web template (see Store source content by using web templates):

  1. In the Name box, enter Coveo Usage Analytics - Push View Event.

  2. In the Website menu, select your portal.

  3. In the Source box, enter the following code:

    <script>
    document.addEventListener('DOMContentLoaded', function() {
      const apiKey = "{{ settings['Coveo/ApiKey'] | default:'' }}";
      const usageAnalyticsUrl = "{{ settings['Coveo/UsageAnalyticsUrl'] | default:'' }}";
      // Currently displayed entity record, passed as an argument by the page that includes this script.
      {% assign entity = entity %}
      // Or, alternatively, a string that indicates the type of the content.
      {% assign content_type = content_type %}
      {% unless content_type or entity %}
      // If content_type isn't defined, try to infer the logical name of the entities in context from the association page.adx_entitylist if it exists.
      {% entitylist id:page.adx_entitylist.id %}
      {% assign content_type = entitylist.entity_logical_name %}
      {% endentitylist %}
      {% endunless %}
      // Arguments of the call to the API.
      let pageViewOptions = undefined;
      {% if entity %}
      // Name of the Coveo Index field that stores the unique ID of a Dynamics entity record.
      let coveoEntityUniqueIdFieldName = "@dycoveoid";
      // Unique ID of the entity record from Dynamics.
      let dynamicsEntityUniqueId = "{{ entity.id }}";
      // Logical name of the entity record from Dynamics.
      let dynamicsEntityLogicalName = "{{ entity.logical_name }}";
      pageViewOptions = {
        contentIdKey: coveoEntityUniqueIdFieldName,
        contentIdValue: dynamicsEntityUniqueId,
        contentType: dynamicsEntityLogicalName
      };
      {% else %}
      // Name of the Coveo Index field that stores the URI of any specific resource.
      let coveoUriFieldName = "@clickableuri";
      // URL to the current page.
      let currentPageUrl = location.href;
      pageViewOptions = {
        contentIdKey: coveoUriFieldName,
        contentIdValue: currentPageUrl,
        contentType: "{{ content_type }}"
      };
      {% endif %}
      if (pageViewOptions) {
      {% if user and user.jobtitle %}
      // Contextual information about the job title or department of the authenticated user, if any.
        pageViewOptions.context_jobtitle = "{{ user.jobtitle }}";
      {% endif %}
      }
      coveoua("init", apiKey, usageAnalyticsUrl);
      coveoua("send", "pageview", pageViewOptions);
    })
    </script>
    

    This sample isn’t necessarily optimal for your use case, as the page visit information it pushes is generic and common to all pages of any portal. Coveo encourages you to tailor this call to your content and needs by adding any piece of contextual information that could be relevant to Coveo Machine Learning (see Coveo Machine Learning and Custom Context Leveraging Leading Practices. For a complete list of the available parameters, see Add a view event via POST.

  4. In the action bar, click Save and close.

Pushing to Coveo UA From an Entity Record Page

Every entity in Dynamics has by default a unique ID field (GUID) that acts as a primary key. In the Coveo Index, this information is stored in the @dycoveoid built-in field.

@dycoveoid is the most reliable unique identifier of an entity record in the Coveo Index. Although @clickableuri also uniquely identifies records most of the time, two different URLs could redirect to the same entity record.

  1. Open the Web Template of the entity record page (e.g., Customer Service - Edit Case).

  2. In the template, locate the Liquid tag that assigns or loads the entity, and then add the following piece of code on the line after the last HTML tag that references this entity:

    {% include 'Coveo Usage Analytics - Push View Event', entity: myEntityVariableInContext %}
    
  3. Replace myEntityVariableInContext in the code snippet with the variable that corresponds to the currently displayed entity (see Available Liquid objects: ‘entities’).

    {% assign incident = entities['incident'][request.params.id] %}
    ...
    {% include 'Coveo Usage Analytics - Push View Event', entity: incident %}
    
  4. At the bottom of the page, click the floppy disk icon to save the template.

Now, whenever a user opens this page, a view event will be pushed through coveoua with the contextual information about the currently displayed entity.

Pushing to Coveo UA From an Entities List Page

If a particular page lists many records of a specific entity type, the URL is usually the proper way to uniquely identify this content. In the Coveo Index, this information is stored into the built-in field @clickableuri.

  1. Open the Web Template of the target page (e.g., Customer Service - Support Home).

  2. In the template, locate the Liquid tag that assigns or loads the entities, and then add the following piece of code on the line after the last HTML tag that references these entities:

    {% include 'Coveo Usage Analytics - Push View Event', content_type: 'logicalNameOfEntityRecordsInContext' %}
    
  3. Replace logicalNameOfEntityRecordsInContext in the code snippet with the logical name of the currently displayed records.

    {% include 'entity_list' key:page.adx_entitylist.id %}
    ...
    {% include 'Coveo Usage Analytics - Push View Event', content_type: 'incident' %}
    
  4. At the bottom of the page, click the floppy disk icon to save the template.

In Coveo Usage Analytics - Push View Event, content_type isn’t restricted to logical names of entities from Dynamics. This argument can be set with the string representation of any relevant content type.

In addition, if no arguments are provided, content_type will be inferred from the logical name of page.adx_entitylist if a value exists (see Dynamics entity tags: ‘entitylist’).

Identifying the User that Opened the Page

For information about how the user is tracked, see Understanding How Coveo Usage Analytics Tracks Users and Sessions.

The current authenticated user, if any, on the portal is available through the user Liquid variable (see Available Liquid objects: ‘user’). In Coveo Usage Analytics - Push View Event, for example, the job title of the current user is passed as contextual information to Coveo UA, providing to Coveo Machine Learning the insight to understand whether a subset of users tend to find a particular item more relevant than users from other departments.

What’s Next?

Optionally, configure additional Coveo for Microsoft Dynamics 365 features to take full advantage of your portal solution (see Optional Features).

Recommended Articles