Relay Reference

This is for:

Developer
Important

The Event Protocol and Coveo Relay library 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

    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

    Returns the first 1024 characters of the current location (URL) context, or null if not available.

    • Returns string | nil

  • getReferrer

    Returns the first 1024 characters of the referring URL, or null if it is not available.

    • Returns string | nil

  • getUserAgent

    Returns the current user agent string, or null if not available.

    • Returns string | nil

  • 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

        Event payload to send.

    • Returns Promise< void >

Properties

  • 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

Meta

The Meta object provides a structured representation of metadata associated with an emitted event. This object is auto-populated by Relay.

Properties

  • clientId: string

    Persistent unique identifier of a device.

  • config: EventConfig

    Configuration associated with the event.

  • location: string | nil

    Browser Location’s href property if set.

  • referrer: string | nil

    Browser Document’s referrer property if set.

  • source: string[]

    Names and versions of the client side libraries which built and emitted this event.

  • ts: number

    Timestamp when the event was emitted.

  • type: string

    Event’s type that was emitted.

  • userAgent: string | nil

    Browser Navigator’s user agent property if set.

Relay

Relay instance. This object provides a comprehensive set of variables and methods for interacting with the Event API.

Functions

  • 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

    Gets the client-side generated meta object.

    • Parameters

      • type: string

        Event’s type that will be included in the meta object.

    • Returns Meta

  • 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

        Callback that should be removed.

    • Returns void

  • 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

        Callback that should be called when the event is emitted.

    • Returns Off

  • updateConfig

    Updates Relay’s configuration after its initialization.

    • Parameters

      • config: Partial< RelayConfig >

        Configuration that should be updated.

    • Returns void

Properties

  • version: string

    Current version of the Relay library.

RelayConfig

The RelayConfig object defines the configuration options for initializing a Relay instance.

Properties

  • environment: 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: 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: 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: string

    Token to authorize the access to the Event API endpoint.

  • trackingId: string | nil

    The unique identifier of a web property. See What’s a tracking ID?. Can be null, in that case events are assigned to an internal default tracking ID.

  • url: string

    Endpoint defined to communicate with the Event API.

RelayEvent

Defines the structure of a RelayEvent, extending the RelayPayload.

Extends RelayPayload

Properties

  • meta: Readonly< Meta >

    Read-only meta property of Meta type.

Functions

createRelay

Initializes the Relay library object.

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 | getClientId | getLocation | getReferrer | getUserAgent | send >

EventCallback

Callback to perform an action when a specified event is emitted.

  • Parameters

    • event: 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 >