Usage
Usage
Relay enables you to send Coveo Usage Analytics (Coveo UA) events to Coveo. This article provides an overview of the core Relay concepts.
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({
token: "<TOKEN>",
trackingId: "<TRACKING_ID>",
url: "https://<ORG_ID>.analytics.org.coveo.com/rest/organizations/<ORG_ID>/events/v1",
});
Initialize a Relay instance using the createRelay function. |
|
Pass in an API key or search token that grants the privileges to push UA data to the target Coveo organization. | |
Specify a unique tracking ID to differentiate and categorize data within your Coveo organization. | |
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({
url: "https://<ORG_ID>.analytics.org.coveo.com/rest/organizations/<ORG_ID>/events/v1",
token: "<TOKEN>",
trackingId: "<TRACKING_ID>",
})
</script>
</head>
</html>
Initialize a Relay instance using the createRelay function and attach it to the window object. |
|
Pass in an API key or search token that grants the privileges to push UA data to the target Coveo organization. | |
Specify a unique tracking ID to differentiate and categorize data within your Coveo organization. | |
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', {
currency: 'USD',
product: {
productId: "SP03929_00014",
name: "Blue Bottle",
price: 16,
},
});
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. |
|
Note
When sending events with Relay, you don’t need to include the
This function is useful to retrieve the |
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) => {
sendProductDataToGoogleAnalytics(event.product);
}
// . . .
relay.on('ec.productView', handleProductView);
// . . .
relay.off('ec.productView', handleProductView); ![3](/en/assets/icons/callouts/3.svg)
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. |
|
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. |
|
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";
// . . .
const ecProductView: Ec.ProductView = {
currency: 'USD',
product: {
productId: "SP03929_00014",
name: "Pluvial Bottle",
price: 16,
},
}
relay.emit('ec.productView', ecProductView); ![3](/en/assets/icons/callouts/3.svg)
Import the Ec namespace which contains the ProductView type. |
|
Use the imported type to define the ecProductView event payload. |
|
Pass in the string name of event and the created payload to the emit function. |
|
Note
When event definitions are updated, |
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.