My Coveo-Powered Search Page

--- title: Log search page usage analytics data to Google Universal Analytics slug: '2943' canonical_url: https://docs.coveo.com/en/2943/ collection: javascript-search-framework source_format: adoc --- # Log search page usage analytics data to Google Universal Analytics [jsui-new 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](https://support.google.com/analytics/answer/11583528). In addition to logging search, click, and custom [events](https://docs.coveo.com/en/260/) to the [Coveo Analytics](https://docs.coveo.com/en/182/) service, the [JavaScript Search Framework](https://docs.coveo.com/en/187/) [`Analytics`](https://coveo.github.io/search-ui/components/analytics.html) component can automatically push events to a properly initialized Google Tag Manager [data layer](https://support.google.com/tagmanager/answer/6164391?hl=en) 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](https://support.google.com/tagmanager/answer/6103696?hl=en)) * A Google Analytics account (see [Get started with Analytics](https://support.google.com/analytics/answer/1008015?hl=en)) ## 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](https://developers.google.com/tag-manager/devguide#adding-data-layer-variables-to-a-page) * [Install your Google Tag Manager container](https://support.google.com/tagmanager/answer/6103696?hl=en#install) * Configure an [`Analytics`](https://coveo.github.io/search-ui/components/analytics.html) component, setting its [`autoPushToGtmDataLayer`](https://coveo.github.io/search-ui/components/analytics.html#options.autoPushToGtmDataLayer) option to `true` > **Note** > > In the unlikely event that you [renamed your data layer](https://developers.google.com/tag-manager/devguide#renaming), be sure to also explicitly specify your non-standard data layer name using the [`gtmDataLayerName`](https://coveo.github.io/search-ui/components/analytics.html#options.gtmdatalayername) option of the `Analytics` component. > > The default and standard data layer name is `dataLayer`. **Example** [,html] ``` My Coveo-Powered Search Page

``` 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. **Examples** * 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](#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](https://support.google.com/analytics/answer/1042508?hl=en) 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: ## 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](https://support.google.com/tagmanager/answer/9207621?hl=en) using the desired tracking ID (see [Get Your Google Analytics Tracking ID](#step-2-get-your-google-analytics-tracking-id)). * [Set up a data layer variable](https://support.google.com/tagmanager/answer/6164391?hl=en) for each `coveoAnalyticsEventData` property you want to be able to leverage in your Google Analytics reports (see [Set Up Your Data Layer Variables](#set-up-your-data-layer-variables)). * [Create a custom event trigger](https://support.google.com/tagmanager/answer/7679219?hl=en) and [**Google Analytics - Universal Analytics** tag](https://support.google.com/tagmanager/answer/6107124?hl=en) 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](#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](https://docs.coveo.com/en/1389/). **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](https://docs.coveo.com/en/1389#submit-user-queries)). In this context, you consider the following `coveoAnalyticsEventData` properties to be especially relevant: * [`actionCause`](https://coveo.github.io/search-ui/interfaces/isearchevent.html#actioncause) * [`actionType`](https://coveo.github.io/search-ui/interfaces/isearchevent.html#actiontype) * [`queryText`](https://coveo.github.io/search-ui/interfaces/isearchevent.html#querytext) * [`numberOfResults`](https://coveo.github.io/search-ui/interfaces/isearchevent.html#numberofresults) 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`): You also create a **Google Analytics Settings** variable, which will be required to configure the tag that will log events to Google Analytics: The following **User-Defined Variables** are now configured in your container: 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`: 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: Finally, you publish your container to make your changes available in the search page in which your container is installed: ### Set up your data layer variables Objects pushed to the data layer by the `Analytics` component implement the [`IAnalyticsEventArgs`](https://coveo.github.io/search-ui/interfaces/ianalyticseventargs.html) 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`](https://coveo.github.io/search-ui/interfaces/isearchevent.html) | `CoveoClickEvent` | [`IClickEvent`](https://coveo.github.io/search-ui/interfaces/iclickevent.html) | `CoveoCustomEvent` | [`ICustomEvent`](https://coveo.github.io/search-ui/interfaces/icustomevent.html) |=== While you could [set up one data layer variable](https://support.google.com/tagmanager/answer/6164391?hl=en) per property that can appear in the `coveoAnalyticsEventData` object, you will typically not need these variables. In particular, the [`coveoAnalyticsEventData.customData`](https://coveo.github.io/search-ui/interfaces/ianalyticsevent.html#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`](https://coveo.github.io/search-ui/interfaces/iclickevent.html#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`](https://coveo.github.io/search-ui/interfaces/iclickevent.html#documentposition)) * The title of the clicked query result item (that is, [`documentTitle`](https://coveo.github.io/search-ui/interfaces/iclickevent.html#documenttitle)) * The URL of the clicked query result item (that is, [`documentUrl`](https://coveo.github.io/search-ui/interfaces/iclickevent.html#documenturl)) * The ranking modifier that was applied to the clicked query result item. (that is, [`rankingModifier`](https://coveo.github.io/search-ui/interfaces/iclickevent.html#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)). ### 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](https://support.google.com/tagmanager/answer/7679219?hl=en). 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](#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](https://support.google.com/tagmanager/answer/9207621?hl=en) configured with the desired tracking ID (see [Get Your Google Analytics Tracking ID](#step-2-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](#set-up-your-data-layer-variables)): * [`actionCause`](https://coveo.github.io/search-ui/interfaces/icustomevent.html#actioncause) (`coveo_actionCause`) * [`actionType`](https://coveo.github.io/search-ui/interfaces/icustomevent.html#actiontype) (`coveo_actionType`) * [`customData`](https://coveo.github.io/search-ui/interfaces/icustomevent.html#customdata)`.pagerNumber` (`coveo_pagerNumber`) Result list paging events are custom events that have the `getMoreResults` value as their `actionType`/[`eventType`](https://coveo.github.io/search-ui/interfaces/icustomevent.html#eventtype) (see [Page query results](https://docs.coveo.com/en/1389#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: 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: ## 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](https://support.google.com/tagmanager/answer/6107163?hl=en). . In your GTM container workspace, [enable preview mode](https://support.google.com/tagmanager/answer/6107056?hl=en). . Open your search page in your browser. . In a new browser window, open your Google Analytics account, and access the [**Real-Time Events** report](https://support.google.com/analytics/answer/1638637?hl=en&ref_topic=1638563). . 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.