Use Relay in Google Tag Manager

This is for:

Developer
Important

The Event Protocol and Coveo Relay are currently in open beta. If you’re interested in using the Event Protocol and Relay library, reach out to your Customer Success Manager (CSM).

This article explains how to set up the use of the Coveo Relay library in the Google 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.

  1. Log in to your GTM account.

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

  3. From the left menu, select Triggers.

  4. Click the New button.

    The trigger card appears.

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

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

  7. Select DOM Ready.

    The Trigger Configuration panel now shows trigger fields and settings.

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

  1. From the left menu, select Tags.

  2. Click the New button.

    The tag card appears.

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

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

  5. Select Custom HTML.

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

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

    <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://staticdev.cloud.coveo.com/relay/v0/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 The type attribute must be set 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.
    3 Pass in an API key or search token that grants the privileges to push analytics data to the target Coveo organization.
    4 Specify a unique tracking ID to differentiate and categorize data within your Coveo organization.
    5 Replace <ORG_ID> with the unique identifier of your Coveo organization to send events to the Event API endpoint.

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

  8. Click the plus icon to create a new trigger.

  9. Select the DOM Ready trigger.

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

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.

  1. From the left menu, select Variables.

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

    The variable card appears.

  3. Enter event variable as the variable name.

    eventProps

    Enter eventProps variable as the variable name when creating a variable for the eventProps property.

  4. In the Variable Configuration panel, click anywhere to open the Choose variable type pane.

  5. For the event variable, select Custom Event.

  6. For the eventProps variable:

    1. Select Data Layer Variable.

      The Variable Configuration panel now shows variable fields and settings.

    2. Specify the following:

      • In the Data Layer Variable Name, enter eventProps.

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

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

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.

  1. From the left menu, select Triggers.

  2. Click the New button.

    The trigger card appears.

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

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

  5. Select Custom Event.

    The Trigger Configuration panel now shows trigger fields and settings.

  6. Specify the following:

    • Fill in the Event name field. For example, productView.

      Important

      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.

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

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

    <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.
    2 As the DataLayer merges the new data with the existing data, it’s not recommended to pass the entire eventProps object as the event payload. Instead, you need to be precise with what values you’re picking from the DataLayer.

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

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

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

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

Click to see the full procedure for creating tags

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

  1. From the left menu, select Tags.

  2. Click the New button.

    The tag card appears.

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

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

  5. Select Custom HTML.

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

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

    <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.
    2 As the DataLayer merges the new data with the existing data, it’s not recommended to pass the entire eventProps object as the event payload. Instead, you need to be precise with what values you’re picking from the DataLayer.

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

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

  7. Click the Advanced Settings option.

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

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

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

  9. Select the trigger you created earlier.

  10. Click the Save button to create the tag.

Check and publish your changes

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

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

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

  3. Open your website in a new tab.

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

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