Use Relay to send events

This is for:

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

Note

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

Note

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({
    token: "<COVEO_API_KEY_OR_SEARCH_TOKEN>", 1
    trackingId: "<TRACKING_ID>", 2
    url: "<COVEO_UA_ENDPOINT>", 3
});
1 Use an API key or search token to authenticate requests to Coveo.
2 Tracking ID
3 Event API endpoint

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

Authentication

Replace <COVEO_API_KEY_OR_SEARCH_TOKEN> with an API key or a search token that grants the Push access level on the Analytics Data domain in the target organization. To use that same API key or search token for your search interface as a whole, also grant it the Allowed access level on the Execute Queries domain privilege.

Important

We strongly recommend that the access token enforces a searchHub value. See Defining the search hub in the authentication for more details.

API key authentication

API key authentication is the simplest option, but doesn’t allow specification of user IDs. In other words, use API key authentication only in anonymous search scenarios.

Note

To improve security, client-side specification of user IDs isn’t supported by Event Protocol. This change from the previous Coveo UA protocol makes it impossible for malicious actors to impersonate others in usage analytics events. To specify user IDs, enforce them through search tokens.

Search token authentication

Search token authentication is the recommended option for logged-in users. This flow requires more setup but is more flexible.

Tracking ID

A Coveo organization can serve many Coveo-powered commerce sites or applications, but all usage analytics events in a user’s journey should be tied together for accurate data analytics and consistency.

tracking IDs segregate the data gathered from each of these sites or applications to ensure personalized and relevant output from your Coveo Machine Learning (Coveo ML) models, usable reporting, and clear merchandising actions.

Each tracking ID points to a specific ecommerce storefront, creating a way to distinguish between distinct sites and their respective user journeys.

The tracking ID is defined when sending events to the Coveo Platform. Interfaces built with the Coveo Headless library or Atomic library automatically include the tracking ID in the events they send. While tracking ID values are specified when sending usage analytics events, each value that’s sent must be registered using a Property in your Coveo organization. To learn how to map your storefront architecture and use tracking IDs in Coveo for Commerce, refer to the Coveo for commerce setup guide.

Example

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 to be sent with each event:

  • barca_sports_us

  • barca_sports_ca

  • barca_parts_us

  • barca_parts_ca

Each of these tracking IDs is registered using a property in your Coveo organization to ensure that the data is correctly sent:

  • Barca Sports US

  • Barca Sports CA

  • Barca Parts US

  • Barca Parts CA

Important

  • The trackingId parameter can only contain lowercase letters, numbers, and underscores (_), such as barca_sports_us1.

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

  • Tracking IDs shouldn’t be confused with other factors such as the site’s domain, locale, or catalog ID.

See What’s a 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

Prod

https://<ORG_ID>.analytics.org.coveo.com/rest/organizations/<ORG_ID>/events/v1

HIPAA

https://<ORG_ID>.analytics.orghipaa.coveo.com/rest/organizations/<ORG_ID>/events/v1

Where <ORG_ID> is the unique identifier of your Coveo organization.