Log View Events

Any page that you want a recommendation interface to recommend typically logs a view event every time it’s opened. Although view events aren’t currently available for usage analytics reports, they’re required to feed Coveo Machine Learning (Coveo ML) Event Recommendation (ER) models.

This article provides guidelines for performing HTTP requests against the Usage Analytics (UA) Write API to properly log view events.

The information in this article is only relevant when you can’t (or choose not to) use the coveoua script to achieve a search integration with the Coveo Platform. Otherwise, the script will handle all HTTP requests on its own, assuming that the coveoua script is used correctly (see Push Coveo Usage Analytics View Events).

To log a view event, make a POST request to

https://analytics.cloud.coveo.com/rest/ua/v15/analytics/view
  • With data residency outside the US, use:

    https://analytics-<REGION_ABBREVIATION>.cloud.coveo.com/rest/ua/v15/analytics/view
  • In the HIPAA environment, use:

    https://analyticshipaa.cloud.coveo.com/rest/ua
  • On Coveo Cloud V1, use:

    https://usageanalytics.coveo.com/rest/v15/analytics/view

Use an access token with the privilege to push analytics data (i.e., the Allowed access level on the Analytics data domain).

EXAMPLE

In the following request, only the body properties which are required by the Coveo Usage Analytics (Coveo UA) and Coveo ML services are included. In this example, even though the username is required, it isn’t included because it’s extracted from the search token. If another authentication method was used, the username field would need to be included in the request body.

POST https://analytics.cloud.coveo.com/rest/ua/v15/analytics/view?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1

Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
Cookie: visitor=28s6g49d-f81s-1435-2r5x153dle72

Payload:

{
  "language": "en",
  "location": "https://docs.coveo.com/en/1243/",
  "contentIDKey": "@permanentid",
  "contentIDValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960"
}

Required Request Body Property

The following property is required by the UA Write API when logging a view event.

location (string)

The URL of the viewed page or component, usually document.location.href.

Coveo ML uses this parameter for debugging purposes.

EXAMPLE
{
  ...
  "location": "https://docs.coveo.com/en/1243/",
  ...
}

Coveo ML-Required Request Body Properties

The following properties aren’t required by the UA Write API when logging a view event, but they’re required when using the Coveo ML service (otherwise, Coveo ML models won’t function properly).

contentIdKey (string)

The name of a field in the index that uniquely identifies the item.

A good practice is to use @permanentid.

Coveo ML ER models use this parameter to match the viewed page or component with the corresponding item in the index.

EXAMPLE
{
  ...
  "contentIDKey": "@permanentid",
  ...
}

contentIdValue (string)

The value of the field selected as contentIDKey. This must not contain any of the following characters: {, }, or :.

This is generally the @permanentid value in the index.

Coveo ML ER models use this parameter to match the viewed page or component with the corresponding item in the index.

EXAMPLE
{
  ...
  "contentIDValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960",
  ...
}

language (string)

The language of the recommendations interface from which the view event originates. This value must be an ISO 639-1 code, and it must match the first part of the locale value in the request body of the corresponding query to the Search API.

Coveo ML builds an independent ER submodel for each language value.

EXAMPLE
{
  ...
  "language": "en",
  ...
}

username (string)

The name of the user security identity which triggered the query that caused the search interface to log a view event. This can only be specified when authenticated with an API key or OAuth2 token with the privilege to impersonate users (i.e., the Allowed access level on the Impersonate domain).

An API key or OAuth2 token with the privilege to impersonate users shouldn’t be exposed publicly.

If username isn’t specified and the request is authenticated with a search token, the service attempts to extract the username value from the access token that authenticated the log view event request. If this fails, username is left blank.

If this isn’t specified and the request is authenticated with an API key, username is set to anonymous.

Coveo ML ER models use username to build user profiles and provide user based recommendations.

EXAMPLE
{
  ...
  "username": "alice.smith@example.com",
  ...
}

Coveo ML-Optional Request Body Properties

The following properties aren’t required by either the UA Write API or Coveo ML service when logging search events. However, specifying values for these properties may improve the effectiveness of Coveo ML.

contentType (string)

The type of content on the page.

When creating a Coveo ML ER model, it’s possible to select the specific contentType values you want to recommend (see Coveo Machine Learning Recommendation Content Types).

EXAMPLE
{
  ...
  "contentType": "Docs",
  ...
}

outcome (integer from -5 to 5)

An indication of the quality of the outcome of this event. A value of -5 corresponds to the worst possible outcome, a value of 0 corresponds to a neutral outcome, and a value of 5 corresponds to the best possible outcome.

The outcome property will eventually be leveraged by the Coveo ML service.

EXAMPLE
{
  ...
  "outcome": 0,
  ...
}

title (string)

The title of the item.

Coveo ML uses this parameter for debugging purposes.

EXAMPLE
{
  ...
  "title": "Coveo for Salesforce",
  ...
}

Optional Request Body Properties

The following properties are entirely optional when logging view events. Although they’re not leveraged by the Coveo ML service nor are they currently available for reporting, you may want to log them because they will eventually be available for reporting.

anonymous (Boolean)

Whether the navigation that caused the recommendations interface to log a view event was triggered by an anonymous user. The default value is false.

If the end user is authenticated but wants to be anonymous, set anonymous to true. The UA Write API won’t extract the name and userDisplayName, if present, from the search token. As long as you don’t attempt to include their identity elsewhere in your request, the end user will remain anonymous.

EXAMPLE
{
  ...
  "anonymous": false,
  ...
}

originContext (string)

The origin of the event. This is used to specify the deployment from which the user performs the action. Suggested values are Search, InternalSearch, CommunitySearch, or the originLevel1 value.

EXAMPLE
{
  ...
  "originContext": "CommunitySearch",
  ...
}

originLevel1 (string)

The name/identifier of the search interface from which the view event originates.

If originLevel1 isn’t specified and the request is authenticated with a search token, the service attempts to extract the searchHub value from the access token that authenticated the log search event request (see Set the Search Hub).

EXAMPLE
{
  ...
  "originLevel1": "ExternalSearch",
  ...
}

originLevel2 (string)

The name/identifier of the tab from which the view event originates.

EXAMPLE
{
  ...
  "originLevel2": "All",
  ...
}

originLevel3 (string)

The URL of the page that redirected the browser to the page from which the view event originates (i.e., document.referrer).

EXAMPLE
{
  ...
  "originLevel3": "https://support.coveo.com/s/search/All/Home/%40uri",
  ...
}

referrer (string)

The URL of the page that redirected the browser to the page from which the view event originates, i.e., document.referrer.

EXAMPLE
{
  ...
  "referrer": "https://support.coveo.com/s/search/All/Home/%40uri",
  ...
}

originLevel3 and referrer fulfill the same purpose. While both properties are exposed for legacy reasons, the best practice is to use originLevel3.

splitTestRunName (string)

The name of the A/B test run, if one is active.

EXAMPLE
{
  ...
  "splitTestRunName": "splitTest",
  ...
}

splitTestRunVersion (string)

The version of the A/B test run, if one is active.

EXAMPLE
{
  ...
  "splitTestRunVersion": "splitTestRunAlpha",
  ...
}

userAgent (string)

Information about the browser and operating system of the end user who navigated to the page that caused the search interface to log a view event.

If the client is performing HTTP requests directly against the UA Write API to log usage analytics events (rather than performing those requests through a proxy server), the browser of the end user will typically include the correct information in the User-Agent request header. In this case, it’s not necessary to specify a value for the userAgent request body property.

EXAMPLE
{
  ...
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.181 Safari/537.36",
  ...
}

userDisplayName (string)

The display name of the user performing the view event.

If userDisplayName isn’t specified and the request is authenticated with a search token, the service attempts to extract the userdisplayName value from the access token that authenticated the log view event request.

EXAMPLE
{
  ...
  "userDisplayName": "Alice",
  ...
}

View Event customData (key-value pairs)

These are custom key-value pairs which can contain all of the user-defined dimensions and their values and can be used for learning. Although view event customData isn’t currently available for reporting, it eventually will be.

  • The customData section must be valid JSON.

  • When possible, we recommend using a string as the value.

  • The value can be any valid JSON, but it’s handled as string over Coveo UA, and the string conversion could result in the alteration of the original JSON. Keys may only contain alphanumeric or underscore characters, and all spaces in the keys are replaced with underscores. Any uppercase characters in the keys are converted to lowercase characters.

EXAMPLES
  • "key" : "value" → This is the recommended format for Coveo UA, which renders the string as "value" and makes it usable as any other string dimension type.

  • "key" : [ "value_1", "value_2" ] → This becomes the string "[ "value_1", "value_2" ] " within Coveo UA. Although it’s harder to use for reporting, this value could still be useful (e.g., when using the filter "contains" type).

  • Any field beginning with context_ will be used by Coveo ML ER as user context to learn and provide boosts to contextually relevant items.

When reporting on view events does become possible, we will highly recommend that you create your custom dimension before adding customData (see Manage Dimensions on Custom Metadata).

EXAMPLE
{
  ...
  "customData":{
    "context_usertype" : "Guest"
  },
  ...
}
Recommended Articles