Log click events

This is for:

Developer

In this article

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

A search interface typically logs a click event when a user clicks or previews a query result.

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

The information in this article is only relevant when you can’t (or choose not to) use one of the Coveo UI libraries (Atomic, Headless, or the JavaScript Search Framework) to achieve a search integration with Coveo. These libraries can handle all of the HTTP requests for you.

To log a click event, make a POST request to

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

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/click

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 Machine Learning (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/click HTTP/1.1

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

Payload:

{
  "anonymous": false,
  "clientId": "489aa3e3-aed2-4563-8e81-62bb73178a56",
  "actionCause": "documentOpen",
  "documentPosition": 2,
  "documentTitle": "Coveo for Salesforce",
  "documentUrl": "https://docs.coveo.com/en/1243/",
  "language": "en",
  "originLevel1": "ExternalSearch",
  "originLevel2": "All",
  "searchQueryUid": "df60b2fb-c276-49ae-b704-2ee45609f3a6",
  "sourceName": "AnswersCloud",
  "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",
  "customData": {
    "contentIDKey": "permanentid",
    "contentIDValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960"
  }
}

Required request body properties

The following properties are required by the UA Write API when logging a click event.

`actionCause` (string)

The identifier of the user action that caused the search interface to log a click event. For example, if the user opens a query result, the standard actionCause value would be documentOpen.

Most of the actions which can be performed from a typical search interface are associated with a specific, standard actionCause value (that is, the one that the Coveo UI libraries would use in a similar situation).

The most common of these are documented in the search interface implementation guidelines.

To learn more about the different actionCause values, see Custom metadata reference.

Note

Some actionCause values are expected to be accompanied by a specific set of customData key-value pairs. Passing these expected key-value pairs is important because they’re used by Coveo ML and in UA reports.

{
  ...
  "actionCause": "documentOpen",
  ...
}

`documentPosition` (unsigned integer)

The position of the item (one-based) that was clicked in the list of results. If unavailable, set to one.

The Coveo ML Query Suggestion (QS) service uses the documentPosition value to judge the quality of suggested results (for example, if a query suggestion is followed by a click event on an item of rank 200, it’s a bad suggestion and should be avoided in the future).

{
  ...
  "documentPosition": 2,
  ...
}

`documentUriHash` (string, deprecated)

The documentUriHash is deprecated, meaning that it’s no longer required.

Instead, you can now provide the clicked item's unique identifier by using the contentIDKey and contentIDValue keys within the customData property.

For example, you can use permanentid as the value for the contentIDKey field and assign the corresponding permanentid value of the clicked item to the contentIDValue field, as follows:

{
  ...
  "customData":{
    "contentIDKey": "permanentid",
    "contentIDValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960",
    ...
  },
  ...
}

The @urihash of the item that was clicked. Maximum: 32 characters.

{
  ...
  "documentUriHash": "xyhvGJJGRDM3OiG5",
  ...
}

`language` (string)

The language of the search interface from which the click 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",
  ...
}

`searchQueryUid` (string)

The unique identifier of the query that caused the search interface to log a click event.

The searchQueryUid value must be the same as the searchUid value in the response of the corresponding search request to the Search API.

The Coveo ML ART and QS models use searchQueryUid to relate click events to search events.

{
  ...
  "searchQueryUid": "df60b2fb-c276-49ae-b704-2ee45609f3a6",
  ...
}

`sourceName` (string)

The @source of the item that was clicked. Maximum: 512 characters.

{
  ...
  "sourceName": "AnswersCloud",
  ...
}

Coveo ML-required request body properties

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

`originLevel1` (string)

The name or identifier of the search interface from which the click 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).

When logging a search event, the originLevel1 value must be the same as the searchHub value in the request body of the corresponding query to the Search API.

Coveo ML models use the originLevel1 value as a default filter field. These filters don’t affect how the models learn, but they must be logged correctly for recommendations to work. When Coveo ML models make suggestions, items which don’t meet the right filters are ignored (see Get query suggestions - Troubleshooting).

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

`contentIDKey` (string)

contentIDKey is a customData field, not a request body property. Coveo ML ART and CR models use this parameter to match the viewed page or component with the corresponding item in the index.

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.

{
  ...
  "customData":{
    ...
    "contentIDKey": "permanentid",
    ...
  },
  ...
}

`contentIDValue` (string)

contentIDValue is a customData field, not a request body property. Coveo ML ART and CR models use this parameter to match the viewed page or component with the corresponding item in the index.

The value of the field selected as contentIDKey. Maximum: 512 characters.

This is generally the permanentid value in the index.

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

`documentTitle` (string)

The title of the item that was clicked. Maximum: 1024 characters.

The documentTitle value must be identical to the value of the title property of the corresponding item in the search request response.

The Coveo ML ART and CR models use documentTitle for debugging.

{
  ...
  "documentTitle": "Coveo for Salesforce",
  ...
}

`documentUrl` (string)

The URL of the item that was clicked. Maximum: 1024 characters.

The documentUrl value must be identical to the value of the uri property of the corresponding item in the search request response.

The Coveo ML ART and CR models use documentUrl to identify items and for debugging.

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

`rankingModifier` (string)

The ranking modifier that affected the clicked item. Maximum: 128 characters.

Note

Although the rankingModifier property isn’t required by the Usage Analytics (UA) Write API, it’s required for the reports on the Visit Browser (platform-ca | platform-eu | platform-au) page.

This corresponds to the rankingModifier property of the result item.

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

{
  ...
  "rankingModifier": "Reveal ART",
  ...
}

`userAgent` (string)

Information about the browser and operating system of the user who caused the search interface to log a click 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",
  ...
}

These bot-generated events are flagged in the Device Category dimension, but they aren’t automatically blocked. However, you can filter them out of reports as needed.

Coveo ML-optional request body properties

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

`originLevel2` (string)

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

When logging a click event, the originLevel2 value must be identical to the tab value in the request body of the corresponding query to the Search API. If there are no tabs in your search interface, you can reuse the searchHub value (in other words, you can use the same value for originLevel1 and originLevel2).

Coveo ML ART models use the originLevel2 value as a default filter field. Filters don’t affect how Coveo ML models learn, but they must be logged correctly for recommendations to work. When Coveo ML models make suggestions, items which don’t meet the right filters are ignored.

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

`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,
  ...
}

Optional request body properties

The following properties are entirely optional when logging click events. Although they’re not leveraged by the Coveo ML service, specifying values for these properties can be useful for reporting.

`anonymous` (Boolean)

Whether the interaction that caused the search interface to log a click 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.

The anonymous value must be identical to the isGuestUser value of the corresponding search request to the Search API. If an authenticated user wants to be anonymous, isGuestUser should be set to true when performing a query.

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

`documentAuthor` (string)

The author of the item that was clicked. Maximum: 128 characters.

{
  ...
  "documentAuthor": "John Doe",
  ...
}

`documentUri` (string)

Deprecated — has no impact.

`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",
  ...
}

`originLevel3` (string)

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

{
  ...
  "originLevel3": "https://docs.coveo.com/en/0/coveo-documentation-for-developers",
  ...
}

`queryPipeline` (string)

The name of the query pipeline which processed the query that led to the click event. Maximum length of 128 characters.

If specified, the queryPipeline value takes precedence over the one defined in the search token pipeline parameter.

If specified, the queryPipeline value must be the same as the pipeline value in the request body of the corresponding query to the Search API.

When performing A/B testing, it’s mandatory to include the queryPipeline in the usage analytics event.

{
  ...
  "queryPipeline": "External Search",
  ...
}

`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",
  ...
}

`userDisplayName` (string)

The display name of the user performing the click 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 click event.

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

`username` (string)

The name of the user security identity which caused the search interface to log a click 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.

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

Click 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).
We recommend that you create your custom dimension before adding customData.
Any field beginning with context_ will be used by Coveo ML as user context to learn and provide boosts to contextually relevant items.
When logging click events, two custom data fields are required for Coveo ML ART and CR: contentIDKey and contentIDValue.

contentIDKey is the name of a field in the index that uniquely identifies the item (this is generally permanentid). contentIDValue is the value of the field selected as contentIDKey. These fields can be found in the search request response, under the raw.permanentid of the clicked item in the result list.

The Coveo ML ART and CR models use these custom data fields to locate the clicked item in the index.

{
  ...
  "customData":{
    "contentIDKey": "permanentid",
    "contentIDValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960",
    "documentTitle": "Coveo for Salesforce",
    "documentURL": "https://docs.coveo.com/en/1243/"
  },
  ...
}

Log click events

Log click events

Example

Required request body properties

actionCause (string)

documentPosition (unsigned integer)

documentUriHash (string, deprecated)

language (string)

searchQueryUid (string)

sourceName (string)

Coveo ML-required request body properties

originLevel1 (string)

contentIDKey (string)

contentIDValue (string)

documentTitle (string)

documentUrl (string)

rankingModifier (string)

userAgent (string)

Coveo ML-optional request body properties

originLevel2 (string)

outcome (integer from -5 to 5)

Optional request body properties

anonymous (Boolean)

documentAuthor (string)

documentUri (string)

originContext (string)

originLevel3 (string)

queryPipeline (string)

splitTestRunName (string)

splitTestRunVersion (string)

trackingId (string)

userDisplayName (string)

username (string)

Click event customData (key-value pairs)

`actionCause` (string)

`documentPosition` (unsigned integer)

`documentUriHash` (string, deprecated)

`language` (string)

`searchQueryUid` (string)

`sourceName` (string)

`originLevel1` (string)

`contentIDKey` (string)

`contentIDValue` (string)

`documentTitle` (string)

`documentUrl` (string)

`rankingModifier` (string)

`userAgent` (string)

`originLevel2` (string)

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

`anonymous` (Boolean)

`documentAuthor` (string)

`documentUri` (string)

`originContext` (string)

`originLevel3` (string)

`queryPipeline` (string)

`splitTestRunName` (string)

`splitTestRunVersion` (string)

`trackingId` (string)

`userDisplayName` (string)

`username` (string)

Click event `customData` (key-value pairs)