Log Coveo Events From Google Tag Manager

Coveo provides a custom Google Tag Manager (GTM) 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 in a Coveo for Commerce solution. You can use the GTM for other methods as well (see Log Search Page Usage Analytics Data to Google Analytics).

A Google Enhanced Ecommerce data layer is required for default tags to work.

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.

Custom legacy events) can be leveraged in Coveo UA reports and by Coveo ML Event Recommendation models.

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 commerce 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.
'impression' The user has viewed information about a product recommendation.
'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.
'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.

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 Create an API Key).

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

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.

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 drop-down, select your variable or create a new one.

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>"
  }
}
What's Next for Me?