--- title: Untitled slug: relay-latest-reference canonical_url: https://docs.coveo.com/en/relay/latest/reference/ collection: relay source_format: adoc --- > **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). ## Interfaces ### `Environment` Platform abstraction interface used by Relay to operate in different execution environments, such as browsers, or custom contexts. #### Functions [#getClientId] * **getClientId** Returns the client identifier synchronously as a UUID string. The returned clientId must be unique per browser instance and stable across sessions with the same top-level domain. The implementation is responsible for generating a valid UUID and persisting it to ensure stability across sessions. ** **Returns** `string` [#getLocation] * **getLocation** Returns the first 1024 characters of the current location (URL) context, or `null` if not available. ** **Returns** `string` | `nil` [#getReferrer] * **getReferrer** Returns the first 1024 characters of the referring URL, or `null` if it is not available. ** **Returns** `string` | `nil` [#getUserAgent] * **getUserAgent** Returns the current user agent string, or `null` if not available. ** **Returns** `string` | `nil` [#send] * **send** Sends an analytics event to the Event API. ** **Parameters** *** **url**: `string` API endpoint where the event should be sent. *** **token**: `string` API token used for authorization. *** **event**: [`RelayEvent`](https://docs.coveo.com/en/relay/latest/reference#relayevent) Event payload to send. ** **Returns** Promise< `void` > #### Properties [#runtime] * **runtime**: `browser` | `null` | `custom` Current runtime context for Relay. It has three possible values. `"browser"` indicates a standard web environment. `"null"` disables all side effects (for example, for unit testing). `"custom"` represents a user-supplied environment. ### `EventConfig` The `EventConfig` object provides additional information for the configuration associated with the event. #### Properties [#trackingId] * **trackingId**: `string` | `nil` The unique identifier of a web property. See [What's a tracking ID?](https://docs.coveo.com/en/n8tg0567/). ### `Meta` The `Meta` object provides a structured representation of metadata associated with an emitted event. This object is auto-populated by Relay. #### Properties [#clientId] * **clientId**: `string` Persistent unique identifier of a device. [#config] * **config**: [`EventConfig`](https://docs.coveo.com/en/relay/latest/reference#eventconfig) Configuration associated with the event. [#location] * **location**: `string` | `nil` Browser Location's [`href`](https://developer.mozilla.org/en-US/docs/Web/API/Location/href) property if set. [#referrer] * **referrer**: `string` | `nil` Browser Document's [referrer](https://developer.mozilla.org/en-US/docs/Web/API/Document/referrer) property if set. [#source] * **source**: `string[]` Names and versions of the client side libraries which built and emitted this event. [#ts] * **ts**: `number` Timestamp when the event was emitted. [#type] * **type**: `string` Event's type that was emitted. [#userAgent] * **userAgent**: `string` | `nil` Browser Navigator's [user agent](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent) property if set. ### `Relay` Relay instance. This object provides a comprehensive set of variables and methods for interacting with the Event API. #### Functions [#emit] * **emit** Sends an event to the Event API. ** **Parameters** *** **type**: `string` Event's type to be emitted. *** **payload**: Record< `string` | `any` > Payload to include within the event. ** **Returns** Promise< `void` > [#getMeta] * **getMeta** Gets the client-side generated meta object. ** **Parameters** *** **type**: `string` Event's type that will be included in the meta object. ** **Returns** [`Meta`](https://docs.coveo.com/en/relay/latest/reference#meta) [#off] * **off** Detach callbacks from events. If only the "type" parameter is set, all callbacks for the specified type will be removed. ** **Parameters** *** **type**: `string` Event's type. *** **callback**: [`EventCallback`](https://docs.coveo.com/en/relay/latest/reference#eventcallback) Callback that should be removed. ** **Returns** `void` [#on] * **on** Attaches an event callback to either all event types or a specific one. The callback set will be called when an event with the specified type is emitted. It’s not possible to modify the payload of the event sent to Coveo using this listener. Setting type as "*" will trigger the callback for all event types. Returns the "off" function to detach the event callback. ** **Parameters** *** **type**: `string` Event's type. *** **callback**: [`EventCallback`](https://docs.coveo.com/en/relay/latest/reference#eventcallback) Callback that should be called when the event is emitted. ** **Returns** [`Off`](https://docs.coveo.com/en/relay/latest/reference#off) [#updateConfig] * **updateConfig** Updates Relay's configuration after its initialization. ** **Parameters** *** **config**: Partial< [`RelayConfig`](https://docs.coveo.com/en/relay/latest/reference#relayconfig) > Configuration that should be updated. ** **Returns** `void` #### Properties [#version] * **version**: `string` Current version of the Relay library. ### `RelayConfig` The `RelayConfig` object defines the configuration options for initializing a Relay instance. #### Properties [#relayconfig-environment] * **environment**: [`CustomEnvironment`](https://docs.coveo.com/en/relay/latest/reference#customenvironment) Optionally allows you to specify a custom environment for Relay, allowing integrations to override the default behavior. This is useful when Relay runs in unsupported or specialized contexts that require custom handling. [#mode] * **mode**: `emit` | `disabled` Defines the library mode. The available modes are `emit` and `disabled`. `emit` sends analytics events to Coveo to be stored. `disabled` prevents the emission of events and does not trigger callbacks. Default: `emit` [#source] * **source**: `string[]` Optionally allows a Relay integration to specify the names of software packages Relay is being called from. These names will be transmitted with each event, along with Relay's own version. The recommendation is to specify them using a 'softwarename@softwareversion' string. [#token] * **token**: `string` Token to authorize the access to the Event API endpoint. [#trackingId] * **trackingId**: `string` | `nil` The unique identifier of a web property. See [What's a tracking ID?](https://docs.coveo.com/en/n8tg0567/). Can be null, in that case events are assigned to an internal default tracking ID. [#url] * **url**: `string` Endpoint defined to communicate with the Event API. ### `RelayEvent` Defines the structure of a RelayEvent, extending the RelayPayload. _Extends_ [`RelayPayload`](https://docs.coveo.com/en/relay/latest/reference#relaypayload) #### Properties [#relayevent-meta] * **meta**: Readonly< [`Meta`](https://docs.coveo.com/en/relay/latest/reference#meta) > Read-only `meta` property of Meta type. ## Functions ### `createRelay` Initializes the Relay library object. * **Parameters** ** **initialConfig**: [`RelayConfig`](https://docs.coveo.com/en/relay/latest/reference#relayconfig) * **Returns** [`Relay`](https://docs.coveo.com/en/relay/latest/reference#relay) ## Type Aliases ### `CustomEnvironment` Partial override of the `Environment` interface, used to customize Relay’s behavior in non-standard browser runtimes. This type allows selective replacement of key environment functions without requiring full control over all `Environment` responsibilities. *** **Type** Pick< [`Environment`](https://docs.coveo.com/en/relay/latest/reference#environment) | `getClientId` | `getLocation` | `getReferrer` | `getUserAgent` | `send` > ### `EventCallback` Callback to perform an action when a specified event is emitted. * **Parameters** ** **event**: [`RelayEvent`](https://docs.coveo.com/en/relay/latest/reference#relayevent) The Relay event payload that triggered the callback. * **Returns** `void` *** **Type** ### `Off` Function that detaches an event callback. * **Returns** `void` *** **Type** ### `RelayPayload` Represents the payload sent with Relay. It is a object with string keys and values of any type. *** **Type** Record< `string` | `any` >