Log Custom Events

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 (e.g., 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 the Coveo JavaScript Search Framework to achieve a search integration with the Coveo Platform. Otherwise, the framework will handle all HTTP requests on its own, assuming that an Analytics component is present in the search interface.

To log a custom event, make a POST request to

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

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

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

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

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) service 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/custom?visitor=28s6g49d-f81s-1435-2r5x153dle72 HTTP/1.1

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

Payload:

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

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.

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

eventValue (string)

The custom event value.

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

language (string)

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

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

ML-Required Request Body Properties

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

Contact the Coveo ML team 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 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.

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

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

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

originContext (string)

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

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

originLevel1 (string)

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

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

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

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

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

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

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

userDisplayName (string)

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

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

username (string)

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

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

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

EXAMPLE
  • "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).

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