Log Coveo events from Google Tag Manager

This is for:

Developer

Through Google Tag Manager (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

The Coveo Usage Analytics library for Commerce was inspired by the Google Universal Analytics library. This article references using the data layer documentation of Google Universal Analytics. Although the syntax has changed in a newer version of Google UA, the Coveo protocol still uses the previous version’s syntax.

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.

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

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

'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).

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

    • checkout

    • checkoutOption

    • productClick

    • refund

    • purchase

    • detailView

    • impression

    Note

    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[1] granting the Push access level on the Analytics Data domain in the target Coveo organization (see Create an API key).

Analytics endpoint (string, required)

The target Coveo environment.

We suggest using Coveo Cloud for most cases, except when 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>"
  }
}
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.