Log search page usage analytics data to Google Universal Analytics

This is for:

Developer

Coveo JavaScript Search Framework v2.6459

Important

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

1.Trigger usage analytics events from a Coveo JavaScript Search Framework interface;2.Fire **Google Analytics - Universal Analytics** tags in Google Tag Manager;3.Visualize Coveo UA data in 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:

Step 1: Configure your search page

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

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

  1. Open your search page in your browser.

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

    Examples

    • Inspecting the data layer right after the search page has been loaded:

      The data layer contains four objects

    • Inspecting the data layer after submitting a query from the search box:

      The data layer contains five objects

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:

Example

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:

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.

Example

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

Google Tag Manager data layer variable configuration for coveo_actionCause using coveoAnalyticsEventData.actionCause and 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:

Google Analytics settings variable configuration showing tracking ID and cookie domain

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

Google Tag Manager user-defined variables list including coveo_actionCause coveo_actionType coveo_numberOfResults coveo_queryText and 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:

Custom Event trigger configuration for CoveoSearchEvent where 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:

Google Analytics Universal Analytics event tag mapped to Coveo data layer variables for category action label and value

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

Google Tag Manager Publish and Create Version screen for sending Coveo search box submit events to Google Analytics

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.

Important

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

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

Note

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

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

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:

Custom Event trigger for CoveoCustomEvent with conditions on pager actionCause and getMoreResults actionType

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:

Google Analytics Universal Analytics event tag for select page of results using Coveo action type cause and pager number variables

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:

  1. Ensure that you have published your GTM container.

  2. In your GTM container workspace, enable preview mode.

  3. Open your search page in your browser.

  4. In a new browser window, open your Google Analytics account, and access the Real-Time Events report.

  5. In your search page, perform the action that should fire your tags.

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

  7. Assuming your tags are firing properly, corresponding new events should appear in your Google Analytics Real-Time Events report.

  8. When you’re done testing, remember to disable preview mode in your GTM container workspace.