Log custom events

This is for:

Developer

In this article

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

Typically, when an end user interacts with a search interface in a way that needs to be recorded, but that isn’t a search, click, or view event (for example, toggling the result list layout or changing end-user preferences), the search interface logs a custom event.

This article provides guidelines for performing HTTP requests against the Usage Analytics (UA) Write API to properly log custom 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 custom event, make a POST request to

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

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

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 Usage Analytics (Coveo UA) service 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/custom HTTP/1.1

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

Payload:

{
  "anonymous": false,
  "eventType": "facet",
  "eventValue": "facetSearch",
  "language": "en",
  "originLevel1": "ExternalSearch",
  "originLevel2": "All",
  "clientId": "489aa3e3-aed2-4563-8e81-62bb73178a56",
}

Required request body properties

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

`eventType` (string)

The custom event type. Maximum: 128 characters.

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

`eventValue` (string)

The custom event value. Maximum: 128 characters.

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

`language` (string)

The language of the search interface from which the custom 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.

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

ML-required request body properties

By default, the Coveo Machine Learning (Coveo ML) Content Recommendation (CR) model doesn’t feed on custom events. However, it’s possible to configure an CR model to feed on custom event data.

Contact your Coveo Customer Success Manager (CSM) or Coveo Support for more information.

Optional request body properties

The following properties are entirely optional when logging custom 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 custom 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,
  ...
}

`lastSearchQueryUid` (string)

The unique identifier of the query that caused 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. This is used to specify the deployment from which the user performs the action. Maximum: 128 characters. Suggested values are Search, InternalSearch, or CommunitySearch.

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

`originLevel1` (string, optional)

The name or identifier of the search interface from which the custom 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 custom event (see Set the Search Hub).

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.

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

`originLevel2` (string)

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

When logging a custom 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).

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

`originLevel3` (string)

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

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

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

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

`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. It 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 custom 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 custom event.

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

`username` (string)

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

Custom 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.

{
  ...
  "customData":{
    "facetId": "@objecttype",
    "facetTitle": "Type"
  },
  ...
}