Relay Reference

This is for:

Developer
Warning

Relay v1 has been deprecated. If you’re implementing Relay, refer to the documentation for the latest version. All new implementations are strongly encouraged to use Event Protocol where practical.

If you’re currently using v1 of Relay, refer to the upgrade guide to update to the latest version.
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

  • generateUUID

    Generates a UUID string.

    • Returns string

  • getLocation

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

    • Returns nil | string

  • getReferrer

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

    • Returns nil | string

  • getUserAgent

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

    • Returns nil | string

  • 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 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.

  • storage: Storage

    Storage implementation used to persist data. Should implement the standard Storage interface.

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: nil | string

    Browser Location’s href property if set.

  • referrer: nil | string

    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: nil | string

    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 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: nil | string

    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.

Storage

Interface that defines a minimal key-value storage mechanism used by Relay.

Functions

  • getItem

    Retrieves the stored string value associated with the specified key. Returns null if the key does not exist or has no value.

    • Parameters

      • key: string

        Key corresponding to the desired value.

    • Returns nil | string

  • removeItem

    Removes the value associated with the specified key from storage. If the key does not exist, no action is taken.

    • Parameters

      • key: string

        Key to remove.

    • Returns void

  • setItem

    Stores a string value under the specified key. Overwrites any existing value.

    • Parameters

      • key: string

        Key under which the value should be stored.

      • data: string

        String data to store.

    • Returns void

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 | generateUUID | getLocation | getReferrer | getUserAgent | send > & Storage

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 >