Using Relay to send events

This is for:

In this article

This article discusses how to use Relay to send events to Coveo Usage Analytics (Coveo UA).

Relay’s initialization options let you authenticate requests and direct them to the correct endpoint. Once set up, Relay actively manages various aspects of generic event logging, including enriching events with browser-specific details like user agent and local time. It also maintains a unique clientId for each browser and device combination.

The following section provides an overview of how to initialize Relay using NPM. For more detailed information on all the available functionality, see the Relay documentation.


When sending events with Relay, you don’t need to send generic user information such as clientId or the timestamp as Relay automatically enriches the events with this information.

Initialize Relay


You can also initialize Relay using a CDN. For more information, see the Using the Relay CDN.

To install the package, run the following command:

npm install @coveo/relay

After installing Relay, initialize the library using the createRelay method:

import { createRelay } from '@coveo/relay';

const relay = createRelay({
    trackingId: "<TRACKING_ID>", 2
    url: "<COVEO_UA_ENDPOINT>", 3

Once an instance of the relay object has been initalized, it can be used to send events using the emit function.

User authentication

Replace <COVEO_API_KEY_OR_SEARCH_TOKEN> in the script with authentication credentials passed in the form of an API key or a search token.

API key

Replace <COVEO_API_KEY_OR_SEARCH_TOKEN> in the script with an API key for Analytics created for your catalog. Upon receipt of a commerce event in Coveo Usage Analytics (Coveo UA), we extract the catalog ID for that event based on the API key.

Before you start, familiarize yourself with the leading practices regarding API keys. To create an API key for Analytics, you must:

  1. Access the Catalogs (platform-ca | platform-eu | platform-au) page.

  2. Click the catalog for which you want to create an API key, and then click Create API Key in the Action bar.

  3. Select API Key for Analytics.

  4. Click Create Key.


The created API key value is unique. It’s impossible to view the value more than once.

If you fail to get the value, delete the lost key and create a new one.

Use the userId field with an API key

Provided that the API key has the necessary impersonate privileges, use the userId field in the payload used to create the API key to log user identities. Replacing <USER_ID> in the script with a value, such as, will log the event under that specific identity. Leaving the field empty will log the event under an anonymous identity.

Search token

An alternate authentication method would be to use a search token when impersonating users, because a search token is temporary and encrypted.

Replace <COVEO_API_KEY_OR_SEARCH_TOKEN> in the script with a search token you create, with the Push access level on the Analytics Data domain and the Allowed access level on the Impersonate domain. The user-specific token will add the user’s information to the event and context which will improve the search experience for the user.


Ensure that you use the impersonate domain of the Analytics service, linked above. Don’t use the Impersonate domain of the Search service, as it will allow users to send queries under any identity.

When creating the token, use the following payload for an unauthenticated user:

    "userIds": [
            "name": "anonymous",
            "provider": "Email Security Provider",
            "type" : "User"

Use a payload similar to the following for an authenticated user (replace with the actual email of the user for whom you’re requesting a search token):

    "userIds": [
            "name": "",
            "provider": "Email Security Provider",
            "type": "User"

Every Coveo organization comes with an Email Security Provider. Hence, the above examples will be compatible by default. If you’re using a custom security identity provider, set the provider parameter to the name of that provider instead.

Tracking ID

A Coveo organization can serve many ecommerce sites or applications. It’s important to segregate the data gathered from each of these sites or applications to ensure personalized and relevant outputs from your Coveo Machine Learning models, as well as usable reporting, and clear merchandising actions.

A tracking ID is a unique identifier used to differentiate and categorize Coveo Usage Analytics (Coveo UA) data by site or app. Similar to the organization ID which identifies the organization itself, the tracking ID points to a specific storefront, creating a way to bucket events belonging to different user journeys.


The trackingId parameter can only contain letters, numbers, hyphens (-), underscores (_), and periods (.). For example, barca_sports_us-2.1.

In a user journey, all events should be tied together for consistency and for accurate data analytics. The tracking ID is therefore the common thread that connects all user actions within a single experience, facilitating the process of analyzing the data including user behavior and preferences.


Your Coveo organization powers two brands: Barca sports and Barca parts. You operate in two different countries: United States and Canada.

Therefore, you have four different sites that require their own unique tracking ID:

  • barca_sports_us

  • barca_sports_ca

  • barca_parts_us

  • barca_parts_ca


A single user journey can’t span multiple tracking IDs, and UA data is segregated by tracking ID. Therefore when you analyze metrics like views, clicks, or conversions, the Advanced Reports will show them for each tracking ID.

+ Additionally, the tracking ID shouldn’t be confused with other factors such as the site’s domain, locale, or catalog ID.

See Tracking ID for more information.

Event API endpoint

To log UA events for an organization, use the Coveo Event API endpoint to send Coveo UA events.

When initializing your library, replace <COVEO_UA_ENDPOINT> with the following:

Coveo Endpoint