Log 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 organization.

This article explains how to use this template.

Step 1: Add the Coveo Analytics Template to Your Workspace

  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

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 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, 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 drop-down 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.

    This tag needs to be the first one that is 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

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

While you can’t 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. Therefore, 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. Ensure that you have configured 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 drop-down 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.

    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 detailed view of a product in your catalog or an add to cart, you should log a send 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).

The following list contains actions you may log as events:

Action Description
'click' The user clicked on a product.
'detail' The user accessed a detailed view of the product.
'quickview' The user accessed a quick view of the product.
'add' or 'remove' The user added or removed a product from their cart.
'purchase' or 'refund' The sale or return of one or more products.
'bookmark_add' or 'bookmark_remove' The user added or removed a product from their bookmark.
'compare_add' or 'compare_remove' The user added a product to compare to another or removed one.
'rating_add' or 'rating_remove' The user added or removed a rating or score on a product.
'review_add' or 'review_remove' The user added or removed a review on a product.
'quote' The user asked for a quote regarding a given product (e.g., asked for a price on a large quantity of products in return for a discount).
'checkout' The user initiated the checkout process for one or more products.
'checkout_option' The user selected an option value for a given checkout step (e.g., selecting payment options or shipping methods).

To 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 have 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 drop-down menu, select Send event.

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

    List of supported triggers:

    • gtm.load (page load)
    • gtm.dom (dom load)
    • addToCart
    • removeFromCart
    • checkout
    • checkoutOption
    • productClick
    • refund
    • purchase
    • detailView
    • impression

    Refer to the events in the Data layer to determine which trigger you should use (e.g., 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 (e.g., Log Product Click to Coveo), and then click Save.

Configure a “Log Custom Coveo 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 Coveo event tag

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

  2. Ensure that you have configured 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 drop-down menu, select Send custom Coveo event.

  7. In the Event metadata section:

    1. Set Event type to a string providing a concise description of a broad category that suits the triggered event (e.g., navigation).

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

    1. Set Language to a valid value.
    2. (Optional) Set additional Document metadata fields.
  9. (Optional) Specify additional Custom metadata.

  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.

Reference

Configuration Settings

The necessary information to initialize the Coveo Analytics script.

API Key (String, Required*)

An API key granting the Push access level on the Analytics Data domain in the target Coveo organization (see User Authentication).

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

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

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.

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