Logging Custom Events

Typically, when the end user interacts with the search interface in a way that needs to be recorded, but that is neither a search, a click, or a view event (e.g., toggling the result list layout, changing end-user preferences), the search interface logs a custom event.

This article provides guidelines for performing HTTP requests against the Usage Analytics Write API to properly log custom events.

The information in this article is only relevant when you cannot (or choose not to) use the Coveo JavaScript Search Framework to achieve a search integration with the Coveo Cloud platform. Otherwise, the framework will handle all HTTP requests on its own, assuming that an Analytics component is present in the search page.

To log a custom event, make a POST request to https://platform.cloud.coveo.com/rest/ua/v15/analytics/custom (or https://usageanalyticshipaa.cloud.coveo.com/rest/v15/analytics/custom in the HIPAA environment, or https://usageanalytics.coveo.com/rest/v15/analytics/custom on Coveo Cloud V1). Use an access token with the privilege to push analytics data (i.e., the Allowed access level on the Analytics data domain) in the target Coveo Cloud organization to authenticate the HTTP request (see Privilege Management and Analytics Data Domain).

A log custom event call in which only the body properties which are required by Coveo Usage Analytics (Coveo UA) are included

POST https://platform.cloud.coveo.com/rest/ua/v15/analytics/custom?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1
 
Content-Type: application/json
Cookie: visitor=28s6g49d-f81s-1435-2r5x153dle72
Authorization: Bearer **********-****-****-****-************

Payload

{
  "anonymous": false,
  "eventType": "facet",
  "eventValue": "facetSearch",
  "language": "en",
  "originLevel1": "ExternalSearch",
  "originLevel2": "All"
}

In the above example, the username is not included, although it is required, since it is extracted from the search token. If another authentication method was used, the username field would need to be included in the request body.

Required Request Body Properties

The following properties are required by the Usage Analytics Write API when logging a custom event:

eventType (string)

The custom event type.

{
  ...
  "eventType": "facet",
  ...
}

eventValue (string)

The custom event value.

{
  ...
  "eventValue": "facetSearch",
  ...
}

language (string)

The language of the search interface from which the custom event originates. Value must be an ISO 639-1 code. Must match the first part of the locale value in the request body of the corresponding query to the Search API, if any.

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

ML-Required Request Body Properties

The Coveo Machine Learning (Coveo ML) Event Recommendations model does not, by default, feed on custom events. That being said, it is possible to configure an Event Recommendations model to feed on custom event data. Contact the machine learning team to learn more.

Optional Request Body Properties

The following request body properties are optional from the Usage Analytics Write API point of view. They are not leveraged in any way by the Coveo ML service. Nevertheless, specifying values for those properties can be useful for reporting purposes.

anonymous (boolean)

Whether the interaction that caused the search interface to log a custom event was triggered by an anonymous user. Default value is false.

If the end user is authenticated, but wants to be anonymous, set anonymous to true. The Usage Analytics Write API will not extract the name and userDisplayName, if present, from the search token. As long as you do not attempt to include the end-user identity anywhere else in your request, the end user will remain anonymous.

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

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

lastSearchQueryUid (string)

The unique identifier of the query that led the search interface to log a custom event.

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

{
  ...
  "lastSearchQueryUid": "7bfc652a-9dea-4811-b3f9-6d24345c37ce"
  ...
}

originContext (string)

The origin of the event. Used to specify the section of the website in which the user performs the action. Suggested values are Search, InternalSearch, or CommunitySearch.

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

originLevel1 (string)

The name/identifier of the search interface from which the custom event originates. If unspecified 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 custom event request.

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

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

originLevel2 (string)

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

When logging a custom event, the originLevel2 value must be the same as the tab value in the request body of the corresponding query to the Search API, if any. If there is no tab in your search interface, you can reuse the searchHub value to fulfill the requirement. In other words, you can use the same value for originLevel1 and originLevel2.

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

originLevel3 (string)

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

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

outcome (integer from -5 to 5)

An indication of how good the outcome of this event is. 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.

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

splitTestRunName (string)

The name of the A/B test run, if one is active. See Adding and Managing A/B Tests.

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

splitTestRunVersion (string)

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

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

userDisplayName (string)

The display name of the user performing the custom event. If unspecified 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 custom event request.

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

username (string)

The name of the user security identity who caused the search interface to log a custom event. Can only be specified when authenticated with an API key or an OAuth2 token with the privilege to impersonate users (i.e., the Allowed access level on the Impersonate domain) (see Privilege Management and Impersonate Domain).

Of course, an API key or an OAuth2 token with the privilege to impersonate users should not be exposed publicly (see Choosing and Implementing a Search Authentication Method).

If unspecified 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 custom event request. If this fails, the username value is left blank.

If unspecified and the request is authenticated with an API key, username is set to platform@coveo.com.

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

Custom Event customData (key-value pairs)

Custom data key-value pairs that can contain all the user-defined dimensions and their values, which can be used for reporting.

  • The customData section must be valid JSON.

  • When possible, it is recommended to use a string as the value.

  • The value could be any valid JSON, but it is handled as string over Coveo UA. The string conversion could result in alteration of the original JSON. Keys can only contain alphanumeric or underscore characters. Spaces in the key are replaced with underscores. Uppercase characters in the key are converted to lowercase characters. ‌

  • "key": "value" → Recommended format for Coveo UA, which will render the string as "value" and make it usable as any other string dimension type over Coveo UA.
  • "key": ["value_1","value_2"] → Will become the string "["value_1","value_2"]" within Coveo UA. Although harder to use for reporting, this value could still be useful (e.g., when using filter "contains" type in Coveo usage analytics).
{
  ...
  "customData":{
    "facetId": "@objecttype",
    "facetTitle": "Type"
  },
  ...
}