Log view events

This is for:

Developer

In this article

Example
Required request body property
Coveo ML-required request body properties
Coveo ML-optional request body properties
Optional request body properties
View event customData (key-value pairs)

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) Content Recommendation (CR) 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 Coveo UA library to send view events to the Coveo Platform. This library will handle all of the HTTP requests for you.

To log a view event, make a POST request to

https://<ORG_ID>.analytics.org.coveo.com/rest/ua/v15/analytics/view

where <ORG_ID> is the unique identifier of your Coveo organization.

In the HIPAA environment, use:

https://<ORG_ID>.analytics.orghipaa.coveo.com/rest/ua/v15/analytics/view

Note

In either case, under the hood, Coveo will use the organization endpoints to redirect your requests to the target region.

Use an access token with the privilege to push UA data (that is, the Allowed access level on the Analytics data domain).

Example

In the following request, only the body properties which are required by the Coveo UA and Coveo ML services are included. In this example, even though the username is required, it’s not 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://myorganizationid9sd8df7s.analytics.org.coveo.com/rest/ua/v15/analytics/view HTTP/1.1

Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload:

{
  "language": "en",
  "clientId": "489aa3e3-aed2-4563-8e81-62bb73178a56",
  "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. Maximum: 1024 characters.

Coveo ML uses this parameter for debugging purposes.

{
  ...
  "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. Maximum: 128 characters.

A good practice is to use the permanentid field.

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

{
  ...
  "contentIdKey": "permanentid",
  ...
}

`contentIdValue` (string)

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

This is generally the permanentid value in the index.

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

{
  ...
  "contentIdValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960",
  ...
}

`language` (string)

The language of the recommendation interface from which the view event originates. Maximum: 256 characters.

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 CR submodel for each language value.

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

`username` (string)

The name of the user security identity which caused the search interface to log a view event. Maximum: 128 characters. This can only be specified when authenticated with an API key or OAuth2 token with the privilege to impersonate users (that is, 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 tries to extract the username value from the access token that authenticated the log search 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.

Note

When the request is authenticated with a search token, and the username is extracted from the token, the username value won’t appear in the event content of the Event browser. To retrieve this value, you’ll need to query the Snowflake database where the username value is stored. This is the only way to reference the username associated with view events when using search token authentication.

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

{
  ...
  "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. Maximum: 128 characters.

When creating a CR model, it’s possible to select the specific contentType values you want to recommend (see Recommendation content types).

{
  ...
  "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.

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

`title` (string)

The title of the item. Maximum: 256 characters.

Coveo ML uses this parameter for debugging purposes.

{
  ...
  "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 search interface to log a view event was triggered by an anonymous user. The default value is false.

If the 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 include their identity elsewhere in your request, the user will remain anonymous.

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

`originContext` (string)

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

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

`originLevel1` (string, optional)

The name or identifier of the search interface from which the view event originates. Maximum: 128 characters.

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

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

`originLevel2` (string)

The name or identifier of the tab from which the view event originates. Maximum: 128 characters.

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

`originLevel3` (string)

The URL of the page that redirected the browser to the page from which the view event originates (that is, document.referrer). Maximum: 128 characters.

{
  ...
  "originLevel3": "https://connect.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, that is, document.referrer.

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

Note

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 to run, if one is active. Maximum: 128 characters.

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

`splitTestRunVersion` (string)

The version of the A/B test to run, if one is active. Maximum: 128 characters.

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

`trackingId` (string)

The value to identify which web property an event is related to. This is a human-readable name you can use when sending analytics events.

{
  ...
  "trackingId": "online_store",
  ...
}

`userAgent` (string)

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

Note

If the client performs HTTP requests directly against the UA Write API to log events (rather than performing those requests through a proxy server), the user’s browser 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.

{
  ...
  "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. Maximum: 128 characters.

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

{
  ...
  "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 which can be used for reporting or learning.

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 (for example, when using the filter "contains" type).
Any field beginning with context_ will be used by Coveo ML as user context to learn and provide boosts to contextually relevant items.

Note

When reporting on view events becomes possible, we will recommend that you create your custom dimension before adding customData.

{
  ...
  "customData":{
    "context_usertype" : "Guest"
  },
  ...
}

Log view events

Log view events

Example

Required request body property

location (string)

Coveo ML-required request body properties

contentIdKey (string)

contentIdValue (string)

language (string)

username (string)

Coveo ML-optional request body properties

contentType (string)

outcome (integer from -5 to 5)

title (string)

Optional request body properties

anonymous (Boolean)

originContext (string)

originLevel1 (string, optional)

originLevel2 (string)

originLevel3 (string)

referrer (string)

splitTestRunName (string)

splitTestRunVersion (string)

trackingId (string)

userAgent (string)

userDisplayName (string)

View event customData (key-value pairs)

`location` (string)

`contentIdKey` (string)

`contentIdValue` (string)

`language` (string)

`username` (string)

`contentType` (string)

`outcome` (integer from `-5` to `5`)

`title` (string)

`anonymous` (Boolean)

`originContext` (string)

`originLevel1` (string, optional)

`originLevel2` (string)

`originLevel3` (string)

`referrer` (string)

`splitTestRunName` (string)

`splitTestRunVersion` (string)

`trackingId` (string)

`userAgent` (string)

`userDisplayName` (string)

View event `customData` (key-value pairs)