Log search page usage analytics data to Google Universal Analytics

This is for:

Developer

In this article

Prerequisites
Step 1: Configure your search page
Step 2: Get your Google Analytics tracking ID
Step 3: Configure your Google Tag Manager container
Step 4: Test your configuration

Coveo JavaScript Search Framework 2.6459 (July 2019)

This article is about Google Universal Analytics (Google UA), not Google Analytics 4.

Google UA is subject to deprecation in 2023.

See Universal Analytics will be going away.

In addition to logging search, click, and custom events to the Coveo Usage Analytics (Coveo UA) service, the JavaScript Search Framework Analytics component can automatically push events to a properly initialized Google Tag Manager data layer object.

While this feature can be used in various ways in Google Tag Manager, this article provides guidelines for leveraging it to log search page usage analytics data to Google Analytics.

Prerequisites

This articles assumes that you have at least basic programming skills and that you have edit access to, as well as some knowledge of how to use:

A Google Tag Manager account (see Setup and install Tag Manager)
A Google Analytics account (see Get started with Analytics)

Step 1: Configure your search page

In the markup of the search page from which you want to log data to Google Analytics:

Set up your data layer
Install your Google Tag Manager container
Configure an Analytics component, setting its autoPushToGtmDataLayer option to true

In the unlikely event that you renamed your data layer, be sure to also explicitly specify your non-standard data layer name using the gtmDataLayerName option of the Analytics component.

The default and standard data layer name is dataLayer.

<head>
  
  <!-- Set up data layer -->
  <script>
    window.dataLayer = [] || window.dataLayer;
  </script>
  
  <!-- Install GTM container -->
  <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
  new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
  j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
  'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
  })(window,document,'script','dataLayer','GTM-XXXXXXX');</script>
  
  <title>My Coveo-Powered Search Page</title>
  <link rel="stylesheet" href="https://static.cloud.coveo.com/searchui/v2.6459/css/CoveoFullSearch.css"/>
  <script class="coveo-script" src="https://static.cloud.coveo.com/searchui/v2.6459/js/CoveoJsSearch.Lazy.min.js"></script>
  <script src="https://static.cloud.coveo.com/searchui/v2.6459/js/templates/templates.js"></script>

  <script>
    const organizationId = 'mycoveoorganization1a2b3c4d';
    const accessToken = '**********-****-****-****-************';
    Coveo.SearchEndpoint.configureCloudV2Endpoint(organizationId, accessToken);
    root = Coveo.$$(document).find('#search');
    Coveo.init(root);
  </script>
</head>
  
<body id="search" class="CoveoSearchInterface">
  
  <!-- Configure Analytics component -->
  <div class="CoveoAnalytics" data-auto-push-to-gtm-data-layer="true"></div>
  
  <!-- ... -->
</body>

To validate your search page configuration:

Open your search page in your browser.
In your browser console, display the content of the data layer object (that is, window.dataLayer).

The data layer should contain a sequence of four objects with the following event values:
- gtm.js
- gtm.dom
- gtm.load
- CoveoSearchEvent
The object whose event value is CoveoSearchEvent corresponds to the event that was logged by the Analytics component when your search interface was loaded.

Whenever you perform an action that triggers a usage analytics event in your search page, the Analytics component should automatically push a corresponding object to the data layer.
- Inspecting the data layer right after the search page has been loaded:
- Inspecting the data layer after submitting a query from the search box:

Step 2: Get your Google Analytics tracking ID

You’ll need a valid Google Analytics tracking ID to be able to configure your Google Tag Manager container (see Step 3: Configure Your Google Tag Manager Container).

If you don’t already have a tracking ID for the search page from which you want to log data to Google Analytics, get one by setting up a property in your Google Analytics account:

You create a new Google Analytics property to track data for the My Coveo-Powered Search Page web site:

**What would you like to track?**: `Website`; **Website Name**: `My Coveo-Powered Search Page`; **Website URL**: `https://search.example.com`; **Industry Category**: `Computers and Electronics`; **Reporting Time Zone**: `United States (GMT-07:00) Los Angeles Time`

Step 3: Configure your Google Tag Manager container

The way you configure your Google Tag Manager container will vary depending on what search page usage analytics data you want to log to Google Analytics.

In general, you must:

Create a Google Analytics settings variable using the desired tracking ID (see Get Your Google Analytics Tracking ID).
Set up a data layer variable for each coveoAnalyticsEventData property you want to be able to leverage in your Google Analytics reports (see Set Up Your Data Layer Variables).
Create a custom event trigger and Google Analytics - Universal Analytics tag for each kind of event you want to be able to log in a specific manner to Google Analytics (see Create Your Triggers and Tags).

For example, you could create three tag/trigger sets: one for search, one for click, and one for custom events. With such a configuration, all events encompassed within the same broad category (that is, search, click, custom) would be logged in the same fashion to Google Analytics.

Alternatively, you could create less generic tag/trigger sets (for example, one for search box submit events, one for item Quick view events, one for result list layout change events, etc.) to gain access to more specific details about end user interactions with your search page in your Google Analytics reports.

For a list of standard usage analytics events logged by the JavaScript Search Framework, see Standard actions and Usage Analytics reference.

You want to log a Google Analytics event whenever an end user submits a query from the search box in your search page (see Submit user queries).

In this context, you consider the following coveoAnalyticsEventData properties to be especially relevant:

Therefore, you set up a coveo_actionCause data layer variable as such (and then repeat a similar process to set up coveo_actionType, coveo_queryText, and coveo_numberOfResults):

**Name**: `coveo_actionCause`; **Variable Type**: `Data Layer Variable`; **Data Layer Variable Name**: `coveoAnalyticsEventData.actionCause`; **Data Layer Version**: `Version 2`

You also create a Google Analytics Settings variable, which will be required to configure the tag that will log events to Google Analytics:

**Name**: `Google Analytics Settings`; **Variable Type**: `Google Analytics Settings`; **Tracking ID**: `UA-012345678-9`; **Cookie Domain**: `auto`

The following User-Defined Variables are now configured in your container:

1. **Name**: `coveo_actionCause`, **Type**: `Data Layer Variable`; 2. **Name**: `coveo_actionType`, **Type**: `Data Layer Variable`; 3. **Name**: `coveo_numberOfResults`, **Type**: `Data Layer Variable`; 4. **Name**: `coveo_queryText`, **Type**: `Data Layer Variable`; 5. **Name**: `Google Analytics Settings`, **Type**: `Google Analytics Settings`

You create a Custom Event trigger that fires when the Analytics component pushes a data layer object whose event value is CoveoSearchEvent and whose coveoAnalyticsEventData.actionCause is searchboxSubmit:

$**Name**: `Coveo UA - Search box submit`; **Trigger Type**: `Custom Event`; **Event name**: `CoveoSearchEvent`; **This trigger fires on**: `{{coveo_actionCause}} equals searchboxSubmit`$

You then configure a Google Analytics - Universal Analytics tag, mapping its event tracking parameters to the desired data layer variables, and associating the tag to your trigger:

$**Name**: `Coveo UA - Send search box submit GA`; **Tag Type**: `Google Analytics - Universal Analytics`; **Track Type**: `Event`; **Category**: `{{coveo_actionType}}`; **Action**: `{{coveo_actionCause}}`; **Label**: `{{coveo_queryText}}`; **Value**: `{{coveo_numberOfResults}}`; **Google Analytics Settings**: `{{Google Analytics Settings}}`; **Firing Triggers**: `Coveo UA - Search box submit`$

Finally, you publish your container to make your changes available in the search page in which your container is installed:

`Publish and Create Version`; **Version Name**: `Send Coveo "Search box submit" to GA`; **Version Description**: `Added data layer variables, trigger, and tag to send Coveo JavaScript Search Framework "Search box submit" events to Google Analytics`; **Publish to Environment**: `Live`

Set up your data layer variables

Objects pushed to the data layer by the Analytics component implement the IAnalyticsEventArgs interface.

The event data of such an object is stored in its coveoAnalyticsEventData property, whose format varies based on the pushed event value:

`event` value	`coveoAnalyticsEventData` format
`CoveoSearchEvent`	`ISearchEvent`
`CoveoClickEvent`	`IClickEvent`
`CoveoCustomEvent`	`ICustomEvent`

While you could set up one data layer variable per property that can appear in the coveoAnalyticsEventData object, you will typically not need these variables. In particular, the coveoAnalyticsEventData.customData property is an object which may itself contain an arbitrary number of key-value pairs. Therefore, you may want to set up data layer variables only for the coveoAnalyticsEventData properties which you plan to leverage.

Remember to set up Version 2 data layer variables, as dot notation is required to access the coveoAnalyticsEventData properties.

You want to log a Google Analytics event whenever an end user clicks a link to open an item in the result list (that is, when a CoveoClickEvent whose coveoAnalyticsEventData.actionCause value is documentOpen is pushed to the data layer).

Looking at the IClickEvent interface documentation, you identify the data you want to use to populate the event tracking parameters of the Google Analytics - Universal Analytics tag that will log such events:

The position of the clicked item in the query results set (that is, documentPosition)
The title of the clicked query result item (that is, documentTitle)
The URL of the clicked query result item (that is, documentUrl)
The ranking modifier that was applied to the clicked query result item. (that is, rankingModifier)

Therefore, you set up a data layer variable for each of those coveoAnalyticsEventData properties.

You also set up a data layer variable for the actionCause property (that is, coveo_actionCause) in order to be able to create a trigger that only fires when the right kind of event is pushed to the data layer (see Create your triggers and tags).

Create your triggers and tags

To be able to log search page usage analytics data to Google Analytics only when specific kinds of events are pushed to the data layer, you must create custom event triggers.

Depending on the type of event you want a given trigger to fire on, you can use the CoveoSearchEvent, CoveoClickEvent, or CoveoCustomEvent value as an Event name when creating a trigger.

If you want a trigger to fire under more specific circumstances (for example, only for a specific type of CoveoCustomEvent), you can add various conditions based on previously defined data layer variables (see Set up your data layer variables).

Of course, triggers are only useful when associated with tags. You must configure one or more Google Analytics - Universal Analytics tags using Event as a Track Type to be able to log search page usage analytics data to Google Analytics.

To create a Google Analytics - Universal Analytics tag, you need a Google Analytics settings variable configured with the desired tracking ID (see Get Your Google Analytics Tracking ID).

You want to log an event to Google Analytics whenever the end user has selected a new page of results to display in the result list (that is, when they navigate to the next page, to the previous page, or to a specific page number).

You have already set up data layer variables for the following coveoAnalyticsEventData properties (see Set Up Your Data Layer Variables):

actionCause (coveo_actionCause)
actionType (coveo_actionType)
customData.pagerNumber (coveo_pagerNumber)

Result list paging events are custom events that have the getMoreResults value as their actionType/eventType (see Page query results). Therefore, when creating your custom event trigger, you use CoveoCustomEvent as an Event name, and add a condition to assert that the coveo_actionType data layer variable has the getMoreResults value.

You don’t want the trigger to fire when the infinite scroll feature is enabled, or when the end user resizes the current page of results. In other words, you don’t want events whose coveo_actionCause value is pagerScrolling or pagerResize to fire the trigger. Therefore, you add one more condition to ensure that the coveo_actionCause data layer variable value is one of pagerNumber, pagerNext, or pagerPrevious.

Your custom event trigger now looks like this:

$**Name**: `Coveo UA - Select page of results`; **Trigger Type**: `Custom Event`; **Event name**: `CoveoCustomEvent`; **This trigger fires on**: `{{coveo_actionCause}} matches RegEx ^pager(Number|Next|Previous)$ AND {{coveo_actionType}} equals getMoreResults`$

You now move on to creating your Google Analytics - Universal Analytics tag.

In Google Analytics, you want to be able to quickly group all events originating from your search page. Consequently, you decide to set the Category event tracking parameter to the hard-coded string Coveo.

To populate the Action parameter with a fairly precise description, you concatenate the values of the coveo_actionType and coveo_actionCause data layer variables.

You find no unique value that could be used to populate the Label parameter, therefore you leave this parameter empty.

Finally, the coveo_pagerNumber data layer variable seems like the logical choice to populate the Value parameter (which must contain a number).

You set your Google Analytics Settings variable and associate the tag to the custom event trigger you just created.

Your Google Analytics - Universal Analytics tag now looks like this:

$**Name**: `Coveo UA - Send select page of results GA`; **Tag Type**: `Google Analytics - Universal Analytics`; **Track Type**: `Event`; **Category**: `Coveo`; **Action**: `{{coveo_actionType}}: {{coveo_actionCause}}`; **Value**: `{{coveo_pagerNumber}}`; **Google Analytics Settings**: `Google Analytics Settings`; **Firing Triggers**: `Coveo UA - Select page of results`$

Step 4: Test your configuration

Once you’ve configured your search page and Google Tag Manager container to log search page usage analytics data to Google Analytics, you will likely want to perform a few tests to ensure that everything is working as expected.

To test your configuration:

Ensure that you have published your GTM container.
In your GTM container workspace, enable preview mode.
Open your search page in your browser.
In a new browser window, open your Google Analytics account, and access the Real-Time Events report.
In your search page, perform the action that should fire your tags.
In the GTM debugging console at the bottom of your search page, validate that your tags are fired, and your data layer variables are populated as expected.
Assuming your tags are firing properly, corresponding new events should appear in your Google Analytics Real-Time Events report.
When you’re done testing, remember to disable preview mode in your GTM container workspace.