Google Analytics and Google Tag Manager Integration

Created by David Argüello Sánchez
Last updated: Oct 06, 2017 by Barbara Mackey (Unlicensed)

Overview

This page contains a guide on how to integrate the Overlay with analytics platforms such as GA or GTM.

Step-by-step guide

Instructions for version 1.4

Version 1.4 introduces a new way to manage custom events that requires a few changes in the Overlay integration snippet. By default, the Overlay provides callbacks to measure the following user events:

  • Query
  • Click
  • Add to cart
  • Opening the Overlay
  • Closing the Overlay

And it also provides a callback to run custom code every time a change in the results set happens.

First of all, please initialize the GA or GTM service (it's just a sample, please use the right parameters for your implementation). This piece of code must be in all the pages that contain the search bar. You can find more detailed instructions in these guides:

GA Code
<!-- Google Analytics -->
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-XXXX-Y', 'auto');
  ga('send', 'pageview');
</script>
<!-- End Google Analytics -->

For GTM there are two options: adding this code in the HTML head tag or adding this code just before the Google Tag Manager code:

GTM Code – Single Tag (Recommended)
<body>
  <script>
    dataLayer = [];
  </script>
  <!-- Google Tag Manager -->
  ...
  <!-- End Google Tag Manager -->

Finally, you can start defining custom callback functions for each type of event.

1. Search tracking

The data object received by the function contains, at least, the following information:

ParameterDescription
qThe query typed by the user
pagePage number for grabbing pagination data
totalHitsNumber of results returned by the query
scopeThe scope that has been set up in the Overlay configuration
langThe language that has been set up in the Overlay configuration
origin

Component of the Overlay where the query was originated. The possible values are:

  • default (search input)
  • empathize_term (click on a term without category in the Empathize)
  • empathize_category (click on a term with category in the Empathize)
  • partial (click on a partial results suggested query)
  • history (click on a user query history entry)
  • spellcheck (click on a spellchecked query)
  • linked (load a URL that already contains a query)
originalQueryOriginal query sent to the API, useful for spellcheck situations

Any other parameter returned by Search&Tagging for your instance will also be part of this object, so our recommendation is to explore all the information it contains using the console.

Search Callback Sample - GA
function searchCallback(data) {
  ga('set', 'page', 'http://site.com/overlay?q=' + data.q);
  ga('send', 'pageview');
  ga('send', 'event', 'EmpathyOverlay', 'search', data.q, data.totalHits);
  // it's just a sample, you can define the GA metric with other parameters
}
Search Callback Sample - Single GTM Tag

This option uses different pieces of code for each event, one Google Analytics trigger, multiple Google Analytics variables, and one Google Analytics tag. The piece of code in the callbacks will be different for different data tracking. If you want to track different data, Google Tag Manager configuration will be the same, and each change must be done in the code.

function searchCallback(data) {
  dataLayer.push({'eventCategory':'EmpathyOverlay', 'eventAction':'search', 'eventLabel':data.q, 'eventValue':1, 'event':'gaEvent'});
  // The chosen keys and values can be different. The keys must have the same name in the code and in Google Tag Manager
}
Search Callback Sample - Multiple GTM Tags

This option uses different pieces of code for each event, different Google Analytics events and different Google Analytics tags. The piece of code in the callbacks will always be the same. If you want to change the data for Google Analytics tracking, each change must be done from Google Tag Manager.

function searchCallback(data) {
  dataLayer.push({'data': data});
  dataLayer.push({'event': 'searchCallback'});
}

2. Product related events tracking (click and add to cart)

The data object received by the function contains, at least, the following information:

ParameterDescription
productIdUnique identifier of the product where the event was triggered
qThe query typed by the user
pagePage number for grabbing pagination data
titleTitle of the product where the event was triggered
urlProduct page URL
scopeThe scope that has been set up in the Overlay configuration
followWhether the user was automatically redirected to the product page after tracking the event (redirection though EmpathyBroker's Stats API)
langThe language that has been set up in the Overlay configuration
Product Event Callback Sample - GA
function clickCallback(data) {
  ga('send', 'event', 'EmpathyOverlay', 'click', data.q);
  // it's just a sample, you can define the GA metric with other parameters
}
Product Event Callback Sample - Single GTM Tag
function clickCallback(data) {
  dataLayer.push({'eventCategory':'EmpathyOverlay', 'eventAction':'click', 'eventLabel':data.q, 'eventValue':1, 'event':'gaEvent'});
  // The chosen keys and values can be different. The keys must have the same name in the code and in Google Tag Manager 
}
Search Callback Sample - Multiple GTM Tags
function clickCallback(data) {
  dataLayer.push({'data': data});
  dataLayer.push({'event': 'clickCallback'});
}

3. Other events

The rest of the events don't provide any additional data to the callback functions and can be tracked in the same way as the above.

4. Update the Overlay initialization snippet using these functions

<script>
  function queryCallback(data) { /* GA or GTM Code */ }
  function clickCallback(data) { /* GA or GTM Code */ }
  function add2cartCallback(data) { /* GA or GTM Code */ }
  function openCallback() { /* GA or GTM Code */ }
  function closeCallback() { /* GA or GTM Code */ }
  function resultsChangeCallback() { /* GA or GTM Code */ }

  EmpathyOverlay.config({
    actionCallbacks: {
      query: queryCallback,
      click: clickCallback,
      add2cart: add2cartCallback,
      open: openCallback,
      close: closeCallback,
      resultsChange: resultsChangeCallback
    }
  });
</script>

Please note that this Overlay feature can be used to run custom code of any other nature, not necessarily related with analytics.

5. Next steps (GTM only)

Single GTM Tag
  1. Go to Google Tag Manager to continue with the integration process. No more code changes are needed.
  2. In Google Tag Manager you have to add triggers. To do it:
    1. Go to Triggers
    2. Click on New
    3. Name: gaEvent
    4. Choose Event: Custom Event
    5. Fire On:
      1. Event name: gaEvent
    6. Create Trigger
  3. Then, you have to create variables for received data in each event. The variables will always be the same, and they must have the dataLayer key names (In this case: eventCategory, eventAction, eventLabel and eventValue). For each of those variables repeat this process:
    1. Go to Variables
    2. At the bottom of the page, in the User-Defined Variables section, click New
    3. Name: One of the dataLayer key names (eventCategory, eventAction, eventLabel and eventValue)
    4. Choose Type: Data Layer Variable
    5. Configure Variable:
      1. Data Layer Variable Name: Same name as the one in point c.
      2. Data Layer Version: Version 2
    6. Create Variable
  4. Finally, a Google Analytics tag must be created. To do it:
    1. Go to Tags
    2. Click on New
    3. Name: gaEvent
    4. Choose Product: Google Analytics
    5. Choose a Tag Type: Google Analytics option you are using
    6. Configure Tag:

      1. Tracking ID: Tracking ID de Google Analytics (UA-XXXXXXXX-X)

      2. Track Type: Event

      3. Category:  {{eventCategory}} //Variable created on point 5

      4. Action: {{eventAction}} //Variable created on point 5

      5. Label: {{eventLabel}} //Variable created on point 5

      6. Value: {{eventValue}} //Variable created on point 5

    7. Fire On: More > Choose from existing Triggers: gaEvent

    8. Create Tag

Multiple GTM tags
  1. Go to Google Tag Manager to continue with the integration process. No more code changes are needed.
  2. In Google Tag Manager you have to add triggers. The next process has to be done for each event:
    1. Go to Triggers
    2. Click on New
    3. Name: Event Name (ebClickCallback, ebSearchCallback or ebConversionCallback)
    4. Choose Event: Custom Event
    5. Fire On:
      1. Event name: The same name of c step.
    6. Create Trigger
  3. Then, you have to create variables for received data in each event. The next process has to be done for each data:
    1. Go to Variables
    2. At the bottom of the page, in the User-Defined Variables section, click New
    3. Name: It should identify the data it represents. For example: Product Name
    4. Choose Type: Data Layer Variable
    5. Configure Variable:
      1. Data Layer Variable Name: One of the Data column values of available data table.
      2. Data Layer Version: Version 2
    6. Create Variable
  4. Finally, Google Analytics tags must be created. These tags depends on the chosen Google Analytics metrics, so the next process describes a general example to track a product click:
    1. Go to Tags
    2. Click on New
    3. Name: GA Overlay Product Click
    4. Choose Product: Google Analytics
    5. Choose a Tag Type: Google Analytics option you are using
    6. Configure Tag:

      1. Tracking ID: Tracking ID de Google Analytics (UA-XXXXXXXX-X)

      2. Track Type: Event

      3. Category: Overlay

      4. Action: {{Event}}

      5. Label: {{Product Name}} (Variable created in Variables section. It represents the product name)

      6. Value: Empty

    7. Fire On: More > Choose from existing Triggers: ebClickCallback

    8. Create Tag

    9. With this tag, when a user clicks in a product, an event in Google Analytics is created with these values:

      1. Event Category: Overlay

      2. Event Action: ebClickCallback

      3. Event Label: Clicked products' name

Instructions for versions 1.2 and 1.3

Note: GTM instructions for these versions live in this separate page.

By default, the Overlay provides callbacks to measure queries and clicks using the GA API in addition to EmpathyBroker Tagging. Simply you should define two functions, one for sending query information to GA and another one for sending clicks information.

First of all, please initialize the GA service (it's just a sample, please use the right parameters for your implementation). You can find more information in this guide.

GA Code
<!-- Google Analytics -->
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-XXXX-Y', 'auto');
  ga('send', 'pageview');
</script>
<!-- End Google Analytics -->

1. Search tracking

The data object received by the function will contain:

ParameterDescription
qThe query typed by the user
pagePage number for grabbing pagination data
totalHitsNumber of results returned by the query
Sample (the function name can be modified)
function searchCallback(data) {
  // ga('set', 'page', 'http://site.com/overlay?q=' + data.q);
  // ga('send', 'pageview');
  // ga('send', 'event', 'Search-Overlay', 'search', data.q, data.totalHits);
  // it's just a sample, you can define the GA metric with other parameters
}

2. Product click tracking

Let us know what data you want to receive in your custom function, by default the title of the clicked resource will be included.

ParameterDescription
qThe query typed by the user
pagePage number for grabbing pagination data
totalHitsNumber of results returned by the query
titleTitle of clicked resource
Sample (the function name can be modified)
function productClickCallback(data) {
  // ga('send', 'event', 'Search-Overlay', 'click', data.q);
  // it's just a sample, you can define the GA metric with other parameters
}

3. Update the Overlay creation using these functions

<link rel="stylesheet" href="https://assets.empathybroker.com/overlay/1.2/css/eb.resources.min.css" />
<script type="text/javascript" src="https://assets.empathybroker.com/overlay/1.2/js/eb.libs.min.js"></script>
<script type="text/javascript" src="https:/assets.empathybroker.com/overlay/1.2/js/eb.resources.min.js"></script>
  
<script type="text/javascript">
	function clickCallback(data) {
		//GA Code
	}
	function searchCallback(data) {
		//GA Code
	}
	function conversionCallback(data) {
		//GA Code
	}

	EmpathyBrokerUI.config('https://{EB_URL}/{EB_INSTANCE_NAME}', {
		lang: 'en',
		displayLang: 'en',
		defaultCurrency: 'EUR',
		scope: 'default',
		pageRows: 12,
		customTrackSearch: searchCallback,
		customTrackClick: clickCallback,
		customTrackConversion: conversionCallback
	}, document.getElementById('EmpathyBrokerUI'));
</script>

Instructions for version 1.1

Note: GTM instructions for these versions live in this separate page.

By default, the Overlay provides callbacks to measure queries and clicks using the GA API in addition to EmpathyBroker Tagging. Simply you should define two functions, one for sending query information to GA and another one for sending clicks information.

First of all, please initialize the GA service (it's just a sample, please use the right parameters for your implementation). You can find more information in this guide.

GA Code
<!-- Google Analytics -->
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-XXXX-Y', 'auto');
  ga('send', 'pageview');
</script>
<!-- End Google Analytics -->

1. Search tracking

The data object received by the function will contain:

ParameterDescription
termThe query typed by the user
pagePage number for grabbing pagination data
numFoundNumber of results returned by the query
Sample (the function name can be modified)
function searchCallback(data) {
  // ga('set', 'page', 'http://site.com/overlay?q=' + data.term);
  // ga('send', 'pageview');
  // ga('send', 'event', 'Search-Overlay', 'search', data.term, data.numFound);
  // it's just a sample, you can define the GA metric with other parameters
}

2. Product click tracking

Let us know what data you want to receive in your custom function, by default the title of the clicked resource will be included.

ParameterDescription
nameDocument name or title
Sample (the function name can be modified)
function productClickCallback(data) {
  // ga('send', 'event', 'Search-Overlay', 'click', data.term);
  // it's just a sample, you can define the GA metric with other parameters
}

3. Update the Overlay creation using these functions

<link rel="stylesheet" href="https://assets.empathybroker.com/overlay/{VERSION}/css/eb.resources.min.css"/>
<script type="text/javascript" src="https://assets.empathybroker.com/overlay/{VERSION}/js/eb.libs.min.js"></script>
<script type="text/javascript" src="https:/assets.empathybroker.com/overlay/{VERSION}/js/eb.resources.min.js"></script>
  
<script type="text/javascript">
  function clickCallback(data) {
    // GA Code
  }

  function searchCallback(data) {
    // GA Code
  }

  function conversionCallback(data) {
    // GA Code
  }

  EmpathyBrokerUI.config('https://{EB_URL}/{EB_INSTANCE_NAME}', {
    lang: 'en',
    displayLang: 'en',
    defaultCurrency: 'EUR',
    scope: 'default',
    pageRows: 12,
    customTrackSearch: searchCallback,
    customTrackClick: clickCallback,
    customTrackConversion: conversionCallback
  }, document.getElementById('EmpathyBrokerUI'));
</script> 

Do you need additional GA metrics to be applied into the Overlay?

Please contact EmpathyBroker Support.