Logging Coveo Events From Google Tag Manager

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

This articles explains how to use this template.

If you need to send 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.

Adding the Coveo Analytics Template to Your Workspace

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

  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.

Configuring an “Initialize the Coveo Analytics Script” Tag

Typically, you should first create a tag whose sole purpose is to initialize the Coveo Analytics script in 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 of your pages.

To configure an Initialize the Coveo Analytics script tag

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

  2. In your Google Tag Manager workspace, 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. In the Action 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.

  8. Click Save.

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

Logging Enhanced Ecommerce Events with the Universal Tracker

Universal Tracker events are used to leverage existing Google Analytics’ Enhanced Ecommmerce metadata which allows Coveo to provide commerce-related recommendations.

Configuring a “Send Universal Tracker Event” Tag

You can use this tag to duplicate the information from Google Analytics Universal Tracker and send it to Coveo.

This is the recommended tag if you already have a Google Analytics Universal Tracker in your Google Tag Manager workspace

To configure a Send Universal Tracker Event tag

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

  2. (Typical prerequisite) Ensure you have configured an Initialize the Coveo Analytics script tag.

  3. In your Google Tag Manager workspace, 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. In the Action menu, select Send Universal Tracker Event.

  7. In the Universal Tracker Configuration section:

    • Set ECommerce variable to a variable that is configured with the ecommerce data layer variable.
      • To create such variable, click on the Choose a variable button on the right of the input.
      • On the top-right on the panel, click on the + sign.
      • As the variable type, select Data Layer variable located in the Page variable section.
      • Set the Data Layer Variable Name to ecommerce.
    • (Optional) Set Visit ID to a UUIDv4 that serves as a unique identifier for the current visitor.
  8. (Optional) If no Initialize the Coveo Analytics script tag fires before this tag, set fields in the Configuration section as required.

  9. Click the Triggering card, and then create or select the trigger that should fire the tag.
    • For this tag, the trigger should match what is currently configured with your Google Analytics Universal Tracker tag.

    To leverage the metadata from a Product Click event, you must configure the trigger to event equals productClick, as specified in the See the Tag Configuration for this Example of the Enhanced Ecommerce Product Clicks event documentation.

  10. Click Save.

  11. In the Rename Tag dialog that appears, enter a meaningful name for your tag (e.g., Coveo Universal Analytics - Log Product Clicks), and then click Save.

Logging Events Without the Universal Tracker

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

Configuring a “Log Custom Event” Tag

You may want to log custom events to record analytics data representing various kinds of end-user actions that fall under none of the other built-in event categories supported by the Coveo Analytics template.

To configure a Log custom event tag

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

  2. (Typical prerequisite) Ensure you have configured an Initialize the Coveo Analytics script tag.

  3. In your Google Tag Manager workspace, 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. In the Action, select Log custom event.

  7. In the Event metadata section:

    • Set Event type to a string providing a concise description of a broad category that suits the triggered event (e.g., navigation).
    • Set Event value to a string providing a concise description of the action that triggered the event (e.g., linkClicked).
  8. In the Document metadata section:

  9. (Optional) Specify additional Custom metadata if desired.

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

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

  12. Click Save.

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

Configuring a “Log Page View Event” Tag

While you cannot leverage page view events in Coveo Cloud usage analytics reports, those events can feed your Coveo Machine Learning (Coveo ML) Event Recommendations (ER) models. Thus, if you want to deploy this feature in your Coveo-powered solution, you should configure a tag that logs page view events.

To configure a Log page view event tag

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

  2. (Typical prerequisite) Ensure you have configured an Initialize the Coveo Analytics script tag.

  3. In your Google Tag Manager workspace, 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. In the Event metadata section:

    • Set Content ID key to a string indicating the name of a field that can uniquely and permanently map the current page back to an item in your Coveo index.
    • Set Content ID value to a string indicating the value of the specified Content ID key field for the Coveo index item corresponding to the current page.
    • Set Content type to a string providing a concise description of the type of content corresponding to the current page (see Coveo Machine Learning Recommendation Content Types).
  7. In the Document metadata section:

  8. (Optional) Specify additional Custom metadata if desired.

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

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

  11. Click Save.

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

Configuring a “Log Product Detail View Event” Tag

Whenever an end user accesses the detailed view of a product in your catalog, you should log a product detail view event. These events are important for Coveo ML to provide relevant commerce-related recommendations, and can also be useful for usage analytics reporting (e.g., to see whether end users viewing detailed product pages end up buying these products).

To configure a Log product detail view event tag

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

  2. (Typical prerequisite) Ensure you have configured an Initialize the Coveo Analytics script tag.

  3. In your Google Tag Manager workspace, 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. in the Action menu, select Log product detail view event.

  7. In the Event metadata section:

    • Set the required basic commerce event metadata fields to valid values.
    • (Optional) Set View duration to a floating point value indicating the amount of time (in seconds) the end user spent viewing the product/variant (e.g., 10.00).
    • (Optional) Set Action cause to a string providing a concise description of the way the end user viewed the product/variant (e.g., View, Quickview, Video, etc.).
    • (Optional) Product name to a string providing the name of the viewed product/variant (e.g., Chair (Blue)).
    • (Optional) Set additional optional basic commerce event metadata fields as desired.
  8. In the Document metadata section:

  9. (Optional) Specify additional Custom metadata if desired.

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

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

  12. Click Save.

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

Configuring a “Log Add to Cart Event” Tag

Add to cart events are important for Coveo ML to provide relevant commerce-related recommendations.

To configure a Log add to cart event tag

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

  2. (Typical prerequisite) Ensure you have configured an Initialize the Coveo Analytics script tag.

  3. In your Google Tag Manager workspace, 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. In the Action menu, select Log add to cart event.

  7. In the Event metadata section:

    • Set the required basic commerce event metadata fields to valid values.
    • (Optional) Set Quantity to a floating point value indicating the number of product units added to the cart (e.g,, 2.0).
    • (Optional) Set Cart ID to a string providing the unique identifier of the target cart (e.g., 97adaba6-b3d7-4354-bd7c-eaa0e60c0539).
    • (Optional) Set additional optional basic commerce event metadata fields as desired.
  8. In the Document metadata section:

  9. (Optional) Specify additional Custom metadata if desired.

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

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

  12. Click Save.

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

Reference

Configuration Settings

The necessary information to initialize the Coveo Analytics script.

API Key (String, Required*)

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

An API key granting the Push access level on the Analytics Data domain in the target Coveo Cloud organization (see Add an API Key).

Analytics Endpoint (String, Required)

The target Coveo Cloud platform environment.

Use Coveo Cloud unless your Coveo Cloud organization is in the HIPAA environment, in which case you must select Coveo Cloud (HIPAA).

Script Version (String)

The version of the Coveo Analytics script to load.

Defaults to the current version of the script.

Required Basic Commerce Event Metadata

The required event metadata fields which are common to Log product detail view event and Log add to cart event Coveo Analytics tags.

Content ID Key (String)

The name of a field that can uniquely and permanently map the current product/variant back to an item in your Coveo index.

Examples:

  • productid
  • sku

Content ID Value (String)

The value of the specified Content ID key field for the Coveo index item corresponding to the current product/variant.

Example: bf79a5b0-b85a-448e-875c-3b46aafe1bea

Optional Basic Commerce Event Metadata

The optional event metadata fields which are common to Log product detail view event and Log add to cart event Coveo Analytics tags.

Parent ID Key (String)

The name of a field that can uniquely and permanently identify the Coveo index item corresponding to the “parent” product, which regroups all other variants of the current product/variant.

Example: parentid

Parent ID Value (String)

The value of the specified Parent ID key field for the Coveo index item corresponding to the “parent” product of the current product/variant.

Example: 4db50da4-3efc-4543-8d2a-a1bf8b700e50

Price (Number)

A decimal value indicating the price of the viewed product/variant.

Example: 12.99

Discounted Price (Number)

A decimal value indicating the price of the viewed product/variant after applying all discounts.

Example: 9.09

Product Categories (Array)

A list of categories associated with the product/variant.

Must yield a JavaScript array of strings.

Example: ["products", "gaming", "mouse"]

Product Brands (Array)

A list of brands associated with the product/variant.

Must yield a JavaScript array of strings.

Example: ["acme", "acmetech"]

Required Document Metadata

The required document metadata field common to all tags whose purpose is to log events.

Language (String)

The language of the current page.

Must yield a valid ISO 639-1.

Example: en

Optional Document Metadata

The optional document metadata fields which are common to all tags whose purpose is to log events.

Location (String)

The URL of the current page.

Defaults to the value yielded by window.location.

Title (String)

The title of the current page.

Defaults to the value yielded by document.title.

Is Anonymous (Boolean)

Whether the current end user is anonymous.

Defaults to false.

Username (String)

The user name to display in usage analytics reports.

Custom Metadata

You can add custom metadata to 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.

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 containing the following JavaScript object:

{
  "isLoggedIn": true
}

merges 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 for usage analytics reporting only, or for Coveo Machine Learning (Coveo ML) model-feeding as well.

  • When Purpose is Usage Analytics Reporting, the keys remain the same in the customData object.
  • When Purpose is Machine Learning Context, the keys include the context_ prefix in the customData object.

If Purpose is Machine Learning Context, the following JavaScript object:

{
  "isLoggedIn": true
}

incorporates the customData sent to Coveo UA as:

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

If Purpose is All, Coveo UA receives a customData object that includes both keys:

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