---
title: Use Relay in Google Tag Manager
slug: relay-latest-gtm
canonical_url: https://docs.coveo.com/en/relay/latest/usage/gtm/
collection: relay
source_format: adoc
---
# Use Relay in Google Tag Manager

> **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).

This article explains how to set up the use of the [Coveo Relay library](https://docs.coveo.com/en/o9je0322/) library in the [Google Tag Manager](https://www.google.com/analytics/tag-manager/) (GTM).

## Create a DOM Ready trigger

If you don't already have a trigger that fires when the DOM is ready, you need to create one.

. Log in to your [GTM account](https://tagmanager.google.com/).

. Navigate to the container where you want to use Relay.

. From the left menu, select **Triggers**.

. Click the **New** button.

The trigger card appears.

. At the top of the card, enter a trigger name, for example, `DOM Ready`.

. In the **Trigger Configuration** panel, click anywhere to open the **Choose trigger type** pane.

. Select **DOM Ready**.

The **Trigger Configuration** panel now shows trigger fields and settings.

. Click the **Save** button to create the trigger.

## Initialize Relay

To use Relay in Google Tag Manager, you need to initialize the Relay library in a Custom HTML tag.

. From the left menu, select **Tags**.

. Click the **New** button.

The tag card appears.

. At the top of the card, enter a trigger name. For example, `Relay initialization`.

. In the **Tag Configuration** panel, click anywhere to open the **Choose tag type** pane.

. Select **Custom HTML**.

The **Tag Configuration** panel now the field for your custom code.

. In the **HTML** field, enter the following code:

```html
<script type="text/gtmscript"> <1>
(function () {
  const done = () => window.google_tag_manager[{{Container ID}}].onHtmlSuccess({{HTML ID}}) <2>

  if (window.relay) return done();

  import("https://static.cloud.coveo.com/relay/v1/relay.min.js").then(
    ({ createRelay }) => {
      window.relay = createRelay({
        token: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", <3>
        trackingId: "your-tracking-id", <4>
        url: "https://<ORG_ID>.analytics.org.coveo.com/rest/organizations/<ORG_ID>/events/v1", <5>
      });

      done();
    }
  );
})();
</script>
```
<1> Set the `type` attribute to `text/gtmscript` to allow the use of `import` in the script.
<2> This function ensures that the tags sequenced after the Relay initialization tag are executed only after the Relay library is loaded.

* The `{{Container ID}}` and `{{HTML ID}}` variables are built-in GTM variables.
To use them, you need to enable them first. See the [Google Tag Manager documentation](https://support.google.com/tagmanager/topic/7182737).
<3> 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 analytics data to the target [Coveo organization](https://docs.coveo.com/en/185/).
<4> Specify a unique [tracking ID](https://docs.coveo.com/en/n8tg0567/) to differentiate and categorize data within your Coveo organization.
<5> Replace `<ORG_ID>` with the [unique identifier](https://docs.coveo.com/en/n1ce5273/) of your Coveo organization to send events to the Event API endpoint.

. In the **Triggering** panel, click anywhere to open the **Choose a trigger** pane.

. Click the plus icon to create a new trigger.

. Select [the **DOM Ready** trigger](#create-a-dom-ready-trigger).

. Click the **Save** button to create the tag.

## Create event variables

You can skip this section if you have variables for the `event` and `eventProps` properties that you're sending from your page via the dataLayer.

**Click to see the full procedure for creating variables**
<details><summary>Details</summary>

To send events to the Coveo Event API, you need to create variables for the `event` and `eventProps` properties that you're sending from your page via the dataLayer.

. From the left menu, select **Variables**.

. In the **User-Defined Variables** section, click the **New** button.

The variable card appears.

. Enter `event variable` as the variable name.

[NOTE]
.eventProps

</details>
Enter `eventProps variable` as the variable name when creating a variable for the `eventProps` property.
#### . In the **Variable Configuration** panel, click anywhere to open the **Choose variable type** pane.

. For the `event variable`, select **Custom Event**.

. For the `eventProps variable`:

.. Select **Data Layer Variable**.

The **Variable Configuration** panel now shows variable fields and settings.

.. Specify the following:

*** In the **Data Layer Variable Name**, enter `eventProps`.

*** In the **Data Layer Version** menu, select **Version 2**.

.. Click the **Save** button.

Now you should have two variables in your GTM, `event` and `eventProps`.
##### == Create event triggers

You may skip this section if you already have triggers for the events that you want to send to the Coveo Event API.

**Click to see the full procedure for creating triggers**
<details><summary>Details</summary>

You need to create a trigger for each event that you want to send to the Coveo Event API.
Here, you'll create a trigger for when a PDP is viewed, but the procedure is similar for any other event.

. From the left menu, select **Triggers**.

. Click the **New** button.

The trigger card appears.

. At the top of the card, enter a trigger name. For example, `PDP view trigger`.

. In the **Trigger Configuration** panel, click anywhere to open the **Choose trigger type** pane.

. Select **Custom Event**.

The **Trigger Configuration** panel now shows trigger fields and settings.

. Specify the following:

** Fill in the **Event name** field. For example, `productView`.

[IMPORTANT]

</details>
The event name must match the event name that you're sending from your page via the dataLayer.
#### ** Select the **Some Custom Events** option.

** Define the trigger conditions based on the variable name and event name. For example, **event variable** > **equals** > **productView**.

. Click the **Save** button to create the trigger.
##### == Create event tags

If you have tags that send events to third-party systems, you need to:

. Update the code to use the Relay library to send events to the Coveo platform.
Here, it's an example of a tag for the `cart action` event, but the procedure is similar for any other event.

```html
<script>
  var props = {{eventProps variable}}
  relay.emit("ec.cartAction", { <1>
    action: props.action, <2>
    currency: props.currency,
    product: props.product,
    quantity: props.quantity,
  });
</script>
```
<1> `ec.cartAction` is the event name the cart actions in the Event API. See the [Event Protocol Reference](https://docs.coveo.com/en/n9da0377#ec.cartaction).
<2> As the DataLayer merges the new data with the existing data, don't pass the entire `eventProps` object as the event payload.
Instead, you need to be precise with what values you're picking from the DataLayer.

. Make sure the Relay initialization tag is sequenced before executing the event tags.

.. Within the tag, click the **Advanced Settings** option.

.. In the **Tag Sequencing** section, select the **Fire a tag before <YOUR_TAG_NAME> fires** checkbox.

.. In the **Setup Tag** field, select the Relay initialization tag.

**Click to see the full procedure for creating tags**
<details><summary>Details</summary>

Here, you'll create a tag for the `PDP view` event, but the procedure is similar for any other event.

. From the left menu, select **Tags**.

. Click the **New** button.

The tag card appears.

. At the top of the card, enter a trigger name. For example, `PDP view tag`.

. In the **Tag Configuration** panel, click anywhere to open the **Choose tag type** pane.

. Select **Custom HTML**.

The **Tag Configuration** panel now shows the field for your custom code.

. In the **HTML** field, enter the following code:

```html
<script>
  var props = {{eventProps variable}}
  relay.emit("ec.productView", { <1>
    currency: props.currency, <2>
    product: props.product,
  });
</script>
```
<1> `ec.productView` is the event name for product views in the Event API. See the [Event Protocol Reference](https://docs.coveo.com/en/n9da0377#ec.productview).
<2> As the DataLayer merges the new data with the existing data, don't pass the entire `eventProps` object as the event payload.
Instead, you need to be precise with what values you're picking from the DataLayer.

To track whether the tag is working, you can add the following code to the tag:

```html
console.log("Relay event : ", {{event variable}});
console.log("Relay event payload : ", props);
```

. Click the **Advanced Settings** option.

.. In the **Tag Sequencing** section, select the **Fire a tag before <YOUR_TAG_NAME> fires** checkbox.

.. In the **Setup Tag** field, select the Relay initialization tag.

. In the **Triggering** panel, click anywhere to open the **Choose a trigger** pane.

. Select the [trigger you created earlier](#create-event-triggers).

. Click the **Save** button to create the tag.

</details>

## Check and publish your changes

Before you publish your changes, check that everything is set up correctly.

. Click the **Preview** button in the upper part of the GTM interface.

. Specify your website URL and click the **Connect** button.

. Open your website in a new tab.

. Examine the console and the network tab in your browser's developer tools to ensure that the Relay library is loaded and that the events are being sent to the Coveo Event API.

. If everything is working as expected, click the **Submit** button in the GTM interface.