Usage

This is for:

Developer

Coveo Relay enables you to send Coveo Usage Analytics (Coveo UA) events to Coveo. This article provides an overview of the core Relay concepts.

Important

The Event Protocol and Coveo Relay are currently in open beta. If you’re interested in using the Event Protocol and Relay library, reach out to your Customer Success Manager (CSM).

Initializing Relay

To initialize Relay, first install the library using either NPM or a CDN. NPM’s ideal for projects needing a specific version and TypeScript IntelliSense. On the other hand, a CDN integration ensures you’re up-to-date with major releases, minimizing major breaking changes.

NPM

Coveo Relay is available as an NPM package.

To install the package, run the following command:

npm install @coveo/relay

All resources will be available under /node_modules/@coveo/relay. You can use these in target pages using <script> tags. Alternatively, If you’re using a module bundler (such as Vite, Rollup, Webpack, etc.), use import {…​} from'@coveo/relay'.

The following sections assume that you’ve installed Relay using NPM and are using a module bundler.

After installing Relay, initialize the library:

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

const relay = createRelay({ 1
    token: "<TOKEN>", 2
    trackingId: "<TRACKING_ID>", 3
    url: "https://<ORG_ID>.analytics.org.coveo.com/rest/organizations/<ORG_ID>/events/v1", 4
});
1 Initialize a Relay instance using the createRelay function.
2 Pass in an API key or search token that grants the privileges to push UA data to the target Coveo organization.
3 Specify a unique tracking ID to differentiate and categorize data within your Coveo organization.
4 Replace <ORG_ID> with the unique identifier of your Coveo organization to send events to the Event API endpoint.

CDN

CDN links are available for the latest Major versions of Relay: https://static.cloud.coveo.com/relay/v<MAJOR_VERSION>/relay.min.js

This method is a safe way to always have the latest features from minor version updates, while avoiding major breaking changes. If you wish to use a specific Minor version of Relay, you can install Relay via NPM. Keep in mind that you’ll need to manually upgrade your installation over time.

After integrating Relay, initialize the library:

<html>
  <head>
    <script type="module">
      import {createRelay} from "https://static.cloud.coveo.com/relay/v0/relay.min.js";

      window.relay = createRelay({ 1
        url: "https://<ORG_ID>.analytics.org.coveo.com/rest/organizations/<ORG_ID>/events/v1", 2
        token: "<TOKEN>", 3
        trackingId: "<TRACKING_ID>", 4
      })
    </script>
  </head>
</html>
1 Initialize a Relay instance using the createRelay function and attach it to the window object.
2 Pass in an API key or search token that grants the privileges to push UA data to the target Coveo organization.
3 Specify a unique tracking ID to differentiate and categorize data within your Coveo organization.
4 Replace <ORG_ID> with the unique identifier of your Coveo organization to send events to the Event API endpoint.

Sending events with Relay

Once you’ve initialized Relay, use the emit function to send events to Coveo. The emit function accepts two parameters: the event type and the event payload.

The event type is the string name of the event, such as ec.productView or itemView, and the event payload is a JSON object containing the data to be sent to Coveo.

Find the list of events accepted by the Event Protocol, along with their required payloads, in the Event Protocol Reference documentation.

The following example showcases how to send an ec.productView event using Relay.

relay.emit('ec.productView', { 1
    currency: 'USD',
    product: {
        productId: "SP03929_00014",
        name: "Blue Bottle",
        price: 16,
    },
});
1 Pass in the name of the event as the first parameter of the emit function. Additionally, pass in the event payload required for the ec.productView event.
Important

When sending events with Relay, you don’t need to include the meta object you see in the Event Protocol Reference documentation, as it’s automatically added by the library. To learn about the meta object that’s added for an event, you can use the getMeta function on the Relay instance by passing in the event type string.

const relay = createRelay({ ... });
meta = relay.getMeta('ec.productView');

This function is useful to retrieve the clientId that Relay uses for sending events.

Using event listeners

Relay offers a flexible approach to handling events through its on and off methods. These methods enable the execution of custom logic in response to specific events. Specifically, these listeners can be used to forward events emitted by Relay to third-party services, such as Google Analytics.

Note

It’s not possible to modify the payload of the event sent to Coveo using these listeners.

The following example showcases how to use the on and off methods to handle the ec.productView event.

import { createRelay } from '@coveo/relay';
import { RelayEvent } from '@coveo/relay';
const handleProductView = (event:RelayEvent) => { 1
    sendProductDataToGoogleAnalytics(event.product);
}
// . . .
relay.on('ec.productView', handleProductView); 2
// . . .
relay.off('ec.productView', handleProductView); 3
1 Define the handleProductView callback function, which contains logic to be extract product data from the event payload and a custom function to send data to Google Analytics.
2 Associate the handleProductView callback function with the ec.productView event. When the event triggers, the callback function executes, enabling custom responses to specific actions or triggers.
3 Detach the handleProductView callback function from the ec.productView event using the off method.

For additional details on the on and off methods, see the Relay object.

Using the relay-event-types package

The relay-event-types NPM package offers automatically generated TypeScript types for events supported by Coveo.

This package enhances type safety, provides auto completion, and offers documentation for event payloads.

The following is an example demonstrating the use of the Ec.ProductView type.

import { Ec } from "@coveo/relay-event-types"; 1
// . . .
const ecProductView: Ec.ProductView = { 2
    currency: 'USD',
    product: {
        productId: "SP03929_00014",
        name: "Pluvial Bottle",
        price: 16,
    },
}

relay.emit('ec.productView', ecProductView); 3
1 Import the Ec namespace which contains the ProductView type.
2 Use the imported type to define the ecProductView event payload.
3 Pass in the string name of event and the created payload to the emit function.
Note

When event definitions are updated, @coveo/relay-event-types is also updated to maintain compatibility with the latest Event API version. To prevent issues with older event definitions, we recommend regularly updating to the latest package version.

Opting-in or out of tracking

You may need to provide users with the ability to opt-in or out of tracking, following the applicable privacy regulations (see Data tracking). To do so, enable or disable Relay using the mode configuration option.

Opt-in

When initializing Relay, set mode to disabled.

const relay = createRelay({
    // ...
    mode: 'disabled',
});

When you’ve obtained consent and are ready to enable UA tracking, set mode to emit using relay.updateConfig (see Functions).

relay.updateConfig({ mode: "emit" });

Opt-out

If a user wants to opt-out of tracking, set mode to disabled.

relay.updateConfig({ mode: "disabled" });

Search events

Since the Event Protocol relies on server-side event logging for search events, independently of Relay, you need to enable or disable UA tracking when making search requests. See Event Protocol: Opting-in or out of tracking.

What’s next?

For detailed information on the library’s functions and interfaces, see the Relay reference documentation.

To understand the types of events you can send using Relay, check out Event Protocol Reference documentation.