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 that 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 Events

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 that you have added the Coveo Analytics template to your workspace.

  2. (Typical prerequisite) Ensure that 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 Usage Analytics (Coveo UA) 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 that you have added the Coveo Analytics template to your workspace.

  2. (Typical prerequisite) Ensure that 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 that you have added the Coveo Analytics template to your workspace.

  2. (Typical prerequisite) Ensure that 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 that you have added the Coveo Analytics template to your workspace.

  2. (Typical prerequisite) Ensure that 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
  }
}
Recommended Articles