Logging Coveo Events From Google Tag Manager

Coveo provides a custom Google Tag Manager template allowing you to easily forward usage analytics data from a Google Tag Manager container to a Coveo Cloud organization.

This articles explains how to import, configure, and use this custom template.

If you need to forward data from a Coveo JavaScript Search Framework interface to Google Analytics through a Google Tag Manager container, see Logging Search Page Usage Analytics Data to Google Analytics

Installing the Coveo Template

This section explains how to download and install the Coveo template for Google Tag Manager.

Step 1 - Download the Template

The template is available here: coveo/coveo-analytics-gtm-template.

You can either clone the repository (recommended), or download the template.tpl file using the Raw button.

Step 2 - Import the Template

  1. In your Google Tag Manager workspace, select the Templates section.

  2. In the Tag Templates card, click New to create a new tag template.

  3. In the top-right corner of the modal, click the three dots (menu) button, and then select Import.

  4. Select the .tpl file downloaded in Step #1.

  5. Click Save, and then close the Template Editor.

Loading the Coveo Analytics Script

  1. In your Google Tag Manager workspace, select the Tags section.

  2. Click New to create a new tag.

  3. Click the Tag Configuration card, and then select the Coveo Analytics tag type.

  4. In the Event Type field, select the Load type.

  5. In the Coveo Analytics API Key field, provide an API key granting the Push privilege in the Analytics Data domain (see Add an API Key and Analytics Data Domain).

  6. Click the Triggering card, and then create or select the trigger for which you want to load the Coveo Analytics script.

    You can create a trigger of type Page View to load the script when any page is being visited.

  7. Click Save and enter a name for your tag (e.g. Coveo Analytics - Load Script).

Logging Custom Events to Coveo Analytics

This section explains how to create Coveo Analytics tags to push custom events to Coveo Usage Analytics (Coveo UA) through Google Tag Manager.

  • You may want to create multiple Coveo Analytics tags to push various kinds of custom events.

  • Coveo Analytics tags only work in pages in which the Coveo Analytics script is loaded (see Loading the Coveo Analytics Script).

  1. In your Google Tag Manager workspace, select the Tags section.

  2. Click New to create a new tag.

  3. Click the Tag Configuration card, and then select the Coveo Analytics tag type.

  4. In the Event dropdown menu, select Custom.

  5. In the Custom Event Metadata section:

    1. In the Event Type box, enter a broad category that suits the triggered event (e.g., navigation).
    2. In the Event Value box, enter a name that describes the action that triggered the event (e.g., linkClicked).
  6. In the Document Metadata section:

    1. In the Language box, create or select a variable that matches the language of the page from which the event is triggered (e.g., a document.documentElement.lang JavaScript variable).
    2. If the default Location (window.location), Title (document.title) , and/or Is Anonymous (false) values do not suit your needs, create or select your own variables for those boxes.
  7. In the Custom Data section, add any extra key-value pairs you want to record for the triggered event (see Adding Custom Metadata).

  8. Click the Triggering card, and then create or select the trigger that will fire the tag.

    You can use a trigger of type Just Links to fire the tag when a link is clicked in a page.

  9. Click the Save button, and then enter a meaningful name for your tag (e.g., Coveo Analytics - Log Link Clicked Event).

Adding Custom Metadata

There are two ways to add custom metadata to an event: specifying key-value pairs, or directly referencing an object stored in a variable.

You can combine both ways in the same tag.

Specifying Key-value Pairs

Specifying custom metadata key-value pairs is useful if you want to fine-tune the metadata for a specific event.

Adding the key isLoggedIn with the variable value {{IsLoggedIn}} would modify the customData object sent to Coveo UA as such:

{
  ...
  "customData": {
    "isLoggedIn": true
  }
}

Adding an Object to Merge

Using an object is useful if you already have a JavaScript object that you want to send as custom metadata with your event.

A variable that contains the following JavaScript object:

{
  "isLoggedIn": true
}

would be merged with the customData object sent to Coveo UA as such:

{
  ...
  "customData": {
    "isLoggedIn": true
  }
}

Custom Metadata Purpose

The Purpose column of the Custom Metadata section allows you to define whether a given custom metadata is intended to be used for usage analytics reporting only, or for Coveo Machine Learning (Coveo ML) model-feeding as well.

If set to Usage Analytics Reporting, the keys and values will be sent to Coveo UA as specified.

If set to Machine Learning Context, the keys will automatically be prefixed with the Machine Learning context prefix, context_.

The following JavaScript object:

{
  "isLoggedIn": true
}

would instead be added in the custom data as

{
  ...
  "customData": {
    "context_isLoggedIn": true
  }
}

If set to All, both keys will be added.

The following JavaScript object:

{
  "isLoggedIn": true
}

would instead be added in the custom data as

{
  ...
  "customData": {
    "isLoggedIn": true,
    "context_isLoggedIn": true
  }
}