Log Coveo events from GTM (Deprecated)

This is for:

Developer
Warning

The Coveo Analytics template for Google Tag Manager (GTM) was written based on the Ecommerce for Tag Manager documentation of Google Universal Analytics.

However, the data layer usage specifications have changed in a newer version of Google UA. In consequence, the template no longer works as expected with the latest version of Google UA and is no longer supported.

This documentation is kept in an archived state for readers who still use the template with the older version of Google UA only.

Through GTM, you can use Custom HTML Tags to send usage analytics data from a Google Tag Manager container to a Coveo organization.

Alternatively, you can use default tags from Coveo’s GTM template. The tags in this template can’t be customized, but can still be used as a quick start to measure analytics.

Important

You must implement a mechanism to prevent logging events when end users reject cookies. Not doing so pollutes your usage analytics data and affects data health.

Step 1: Add the Coveo Analytics template to your workspace

Warning

The Coveo Analytics template for Google Tag Manager (GTM) was written based on the Ecommerce for Tag Manager documentation of Google Universal Analytics.

However, the data layer usage specifications have changed in a newer version of Google UA. In consequence, the template no longer works as expected with the latest version of Google UA and is no longer supported.

This documentation is kept in an archived state for readers who still use the template with the older version of Google UA only.

  1. In your Google Tag Manager workspace, in the left navigation, select Templates.

  2. In the Tag Templates card, click Search Gallery.

  3. In the Community Template Gallery panel that appears, search for coveo, and then select the Coveo Analytics template. Coveo Google Tag Manager Gallery

  4. Click Add to workspace.

  5. In the Are you sure you want to add a community template? dialog that appears, click Add.

Step 2: Configure the Initialize the Coveo Analytics script tag

Warning

The Coveo Analytics template for Google Tag Manager (GTM) was written based on the Ecommerce for Tag Manager documentation of Google Universal Analytics.

However, the data layer usage specifications have changed in a newer version of Google UA. In consequence, the template no longer works as expected with the latest version of Google UA and is no longer supported.

This documentation is kept in an archived state for readers who still use the template with the older version of Google UA only.

Typically, you should first create a tag whose sole purpose is to initialize the Coveo Analytics script on the pages from which you want to log events. This tag centralizes the basic required configuration settings and allows you to determine precisely when to initialize the script in all your pages.

Configure an Initialize the Coveo Analytics script tag

  1. Add the Coveo Analytics template to your workspace.

  2. In your Google Tag Manager workspace, in the left-navigation, select the Tags section.

  3. In the Tags card, click New.

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

  5. From the Action dropdown menu, select Initialize the Coveo Analytics script.

  6. In the Configuration section, set the required fields.

  7. Click the Triggering card, and then create or select the trigger that should fire the tag.

    Important

    This tag needs to be the first one that’s fired on the page, so select a trigger that will fire early.

  8. Click Save.

  9. In the Rename Tag dialog that appears, enter a meaningful name for your tag, and then click Save.

Step 3: Log events

Warning

The Coveo Analytics template for Google Tag Manager (GTM) was written based on the Ecommerce for Tag Manager documentation of Google Universal Analytics.

However, the data layer usage specifications have changed in a newer version of Google UA. In consequence, the template no longer works as expected with the latest version of Google UA and is no longer supported.

This documentation is kept in an archived state for readers who still use the template with the older version of Google UA only.

Once the Coveo Analytics script is initialized, you’re ready to log any number of events in your page. This section describes the tags that you can use.

Configure a log page view event tag

To configure a Log page view event tag

  1. Add the Coveo Analytics template to your workspace.

  2. Configure an Initialize the Coveo Analytics script tag.

  3. In your Google Tag Manager workspace, in the left-navigation, select the Tags section.

  4. In the Tags card, click New.

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

  6. From the Action dropdown menu, select Send page view.

  7. (Optional) If no Initialize the Coveo Analytics script tag fires before this tag, set fields in the Configuration section as required.

    Note

    You only need to set the Configuration once, on the first event of the page.

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

  9. Click Save.

  10. In the Rename Tag dialog that appears, enter a meaningful name for your tag, and then click Save.

Configure a log event tag

Whenever an end user accesses the product detail view in your commerce catalog or an add to cart, you would send that specific event tag. These events are important for Coveo ML to provide relevant commerce-related recommendations, and can also be useful for usage analytics reporting. For example, to see whether end users viewing a product detail page end up purchasing those products.

The following list contains required commerce-related user actions you may log as events:

Action Description 'click'

The user clicked a product.

'add' or 'remove'

The user added or removed a product from their cart.

'detail'

The user accessed a product detail page.

'purchase'

Configure a Log event tag.

  1. Ensure that you have added the Coveo Analytics template to your workspace.

  2. Ensure the event you want to log can be found in the Data layer.

  3. Ensure that you’ve configured an Initialize the Coveo Analytics script tag.

  4. In your Google Tag Manager workspace, in the left-navigation, select the Tags section.

  5. In the Tags card, click New.

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

  7. From the Action dropdown menu, select Send event.

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

    Select from the following triggers:

    • gtm.load (page load)

    • gtm.dom (dom load)

    • addToCart

    • removeFromCart

    • productClick

    • purchase

    • detailView

    Note

    Refer to the events in the Data layer to determine which trigger you should use. For example, to measure a product click as the event, you would use productClick.

  9. Click Save.

  10. In the Rename Tag dialog that appears, enter a meaningful name for your tag, and then click Save.

Reference

Warning

The Coveo Analytics template for Google Tag Manager (GTM) was written based on the Ecommerce for Tag Manager documentation of Google Universal Analytics.

However, the data layer usage specifications have changed in a newer version of Google UA. In consequence, the template no longer works as expected with the latest version of Google UA and is no longer supported.

This documentation is kept in an archived state for readers who still use the template with the older version of Google UA only.

Configuration settings

The necessary information to initialize the Coveo Analytics script.

API key (string, required)

An API key[1] granting the Push access level on the Analytics Data domain in the target Coveo organization (see Create an API key).

1. Required only when the selected Action menu option is Initialize the Coveo Analytics script, or when no Initialize the Coveo Analytics script tag fires before a tag that logs an event.

Analytics endpoint (string, required)

The target Coveo Platform environment.

For most cases, consider using Coveo Cloud unless your Coveo organization operates within the HIPAA environment. In that situation, you should choose Coveo Cloud (HIPAA).

Additionally, you have the option to personalize the analytics endpoint by using a custom variable. You can either update the endpoint to a URL specific to your organization or select an endpoint that suits your region. For more details, refer to the Organization endpoints section.

Script version (string, optional)

The version of the Coveo Analytics script to load.

Defaults to the current version of the script.

Custom event document metadata

The document metadata fields common to all tags whose purpose is to log custom events.

Language (string, required)

The language of the current page.

Must be a valid ISO 639-1 code.

Example: en

Location (string, optional)

The URL of the current page.

Defaults to the value yielded by window.location.

Title (string, optional)

The title of the current page.

Defaults to the value yielded by document.title.

Is anonymous (boolean, optional)

Whether the current end user is anonymous.

Defaults to false.

Username (string, optional)

The user name to display in usage analytics reports.

Override metadata

You can override the metadata on an event by specifying key-value pairs, or by directly referencing an object stored in a variable. You can also combine both approaches in the same tag. Adding an unknown attribute will just ignore the metadata.

Specify key-value pairs

Specifying override metadata key-value pairs is useful if you want to fine-tune the metadata for a specific event. To do so, click Add Row and enter the Key and Value.

Example

If the default browser language is en-US, and you need to override the default browser language, adding the key language with the variable value fr would override the metadata sent to Coveo UA as such:

{
    "language": "fr"
}

Add an object to merge

Using an object to merge is useful when you want to take multiple keys that already exist in a JavaScript object and apply the override to multiple values in one event.

To do so, click Add Row and from the dropdown menu, select your variable or create a new one.

Example

To add keys that don’t exist in the protocol, adding a custom key followed by an object { "<MY_CUSTOM_KEY>" : "<VALUE>" } will override that metadata at the root level.

{
  "custom": {
    "<MY_CUSTOM_KEY>": "<VALUE>"
  }
}