Log Coveo events from Google Tag Manager
Log Coveo events from Google Tag Manager
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.
|
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
-
In your Google Tag Manager workspace, in the left navigation, select Templates.
-
In the Tag Templates card, click Search Gallery.
-
In the Community Template Gallery panel that appears, search for
coveo
, and then select the Coveo Analytics template. -
Click Add to workspace.
-
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
-
Ensure that you have added the Coveo Analytics template to your workspace.
-
In your Google Tag Manager workspace, in the left-navigation, select the Tags section.
-
In the Tags card, click New.
-
Click the Tag Configuration card, and then select the
Coveo Analytics
custom tag type. -
From the Action dropdown menu, select
Initialize the Coveo Analytics script
. -
In the Configuration section, set the required fields.
-
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.
-
Click Save.
-
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
-
Ensure that you have added the Coveo Analytics template to your workspace.
-
Ensure that you have configured an
Initialize the Coveo Analytics script
tag. -
In your Google Tag Manager workspace, in the left-navigation, select the Tags section.
-
In the Tags card, click New.
-
Click the Tag Configuration card, and then select the
Coveo Analytics
custom tag type. -
From the Action dropdown menu, select Send page view.
-
(Optional) If no
Initialize the Coveo Analytics script
tag fires before this tag, set fields in the Configuration section as required.NoteYou only need to set the Configuration once, on the first event of the page.
-
Click the Triggering card, and then create or select the trigger that should fire the tag.
-
Click Save.
-
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 |
---|---|
|
The user clicked on a product. |
|
The user accessed a detailed view of the product. |
|
The user accessed a quick view of the product. |
|
The user added or removed a product from their cart. |
|
The sale or return of one or more products. |
|
The user added or removed a product from their bookmark. |
|
The user added a product to compare to another or removed one. |
|
The user added or removed a review on a product. |
|
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). |
|
The user initiated the checkout process for one or more products. |
|
The user selected an option value for a given checkout step (e.g., selecting payment options or shipping methods). |
Configure a Log event
tag
-
Ensure that you have added the Coveo Analytics template to your workspace.
-
Ensure the event you want to log can be found in the Data layer.
-
Ensure that you have configured an
Initialize the Coveo Analytics script
tag. -
In your Google Tag Manager workspace, in the left-navigation, select the Tags section.
-
In the Tags card, click New.
-
Click the Tag Configuration card, and then select the
Coveo Analytics
custom tag type. -
From the Action dropdown menu, select
Send event
. -
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
NoteRefer 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
). -
-
Click Save.
-
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
.
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.
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>"
}
}
Initialize the Coveo Analytics script
, or when no Initialize the Coveo Analytics script
tag fires before a tag that logs an event.