--- title: Usage slug: relay-latest-usage canonical_url: https://docs.coveo.com/en/relay/latest/usage/ collection: relay source_format: adoc --- # Usage [Coveo Relay library](https://docs.coveo.com/en/o9je0322/) enables you to send [Coveo Analytics](https://docs.coveo.com/en/182/) events to Coveo. This article provides an overview of the core Relay concepts. > **Important** > > The [Event Protocol](https://docs.coveo.com/en/o9je0592/) and [Coveo Relay library](https://docs.coveo.com/en/o9je0322/) are generally available for Commerce. > > However, they're in closed beta for Coveo for Service, Website, and Workplace implementations. > If you're interested in using the Event Protocol and Relay library for these implementations, contact 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](https://www.npmjs.com/package/@coveo/relay). To install the package, run the following command: ```bash npm install @coveo/relay ``` All resources will be available under `/node_modules/@coveo/relay`. You can use these in target pages using ` ``` <1> Initialize a [`Relay`](https://docs.coveo.com/en/relay/latest/reference#relay) instance using the [`createRelay`](https://docs.coveo.com/en/relay/latest/reference#createrelay) function and attach it to the `window` object. <2> Pass in an [API key](https://docs.coveo.com/en/105/) or [search token](https://docs.coveo.com/en/56/) that grants the [privileges](https://docs.coveo.com/en/228/) to push UA data to the target [Coveo organization](https://docs.coveo.com/en/185/). <3> Specify a unique [tracking ID](https://docs.coveo.com/en/n8tg0567/) to differentiate and categorize data within your Coveo organization. <4> Replace `` with the [unique identifier](https://docs.coveo.com/en/n1ce5273/) 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](https://docs.coveo.com/en/n9da0377/) documentation. The following example showcases how to send an `ec.productView` event using Relay. ```js 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`](https://docs.coveo.com/en/n9da0377#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`. > [.highlight] > ```js 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. ```js 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](https://docs.coveo.com/en/relay/latest/reference#relay) object. ### Using the `relay-event-types` package The [`relay-event-types`](https://www.npmjs.com/package/@coveo/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. ```js 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, regularly update 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](https://docs.coveo.com/en/3348/)). To do so, enable or disable Relay using the `mode` configuration option. ### Opt-in When [initializing Relay](#initializing-relay), set `mode` to `disabled`. ```js 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](https://docs.coveo.com/en/relay/latest/reference#functions)). ```js relay.updateConfig({ mode: "emit" }); ``` ### Opt-out If a user wants to opt-out of tracking, set `mode` to `disabled`. ```js 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](https://docs.coveo.com/en/o3r90189#opting-in-or-out-of-tracking). ## What's next? For detailed information on the library's functions and interfaces, see the [Relay reference documentation](https://docs.coveo.com/en/relay/latest/reference). To understand the types of events you can send using Relay, check out [Event Protocol Reference documentation](https://docs.coveo.com/en/n9da0377/).