Google Analytics and Google Tag Manager Integration

Overview

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

• Instructions for version 1.4

• Instructions for version 1.3

• Instructions for version 1.2

• Instructions for version 1.1

• Interface X integration

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:

• https://developers.google.com/analytics/devguides/collection/analyticsjs/

• https://support.google.com/tagmanager/answer/6103696
  
  
  

GA Code

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)

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:

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

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.

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.

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

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

Product Event Callback Sample - GA

Product Event Callback Sample - Single GTM Tag

Search Callback Sample - Multiple GTM Tags

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

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:

   7.  

      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

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

   9. 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:

   7.  

      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

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

   9. Create Tag

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

   11.  

       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

1. Search tracking

The data object received by the function will contain:

Sample (the function name can be modified)

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.

Sample (the function name can be modified)

3. Update the Overlay creation using these functions

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

1. Search tracking

The data object received by the function will contain:

Sample (the function name can be modified)

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.

Sample (the function name can be modified)

3. Update the Overlay creation using these functions

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

Please contact EmpathyBroker Support.

Interface X archetype integration

To integrate the Interface X Archetype layer in a commerce store, load the generated Interface X JavaScript file and initialize it.

Depending on your business needs, Interface X supports two initialisation types:

• Automatic initialisation

• On-demand initialisation

Initializing the Interface X project automatically

Steps to initialize the project automatically:

1. Configure the JavaScript snippet to define either an initialization object or a function.

2. Load and initialize the Interface X script.

Configuring the snippet

First, add the JavaScript snippet configuration to define multiple initialization options, i.e. the API to use, the language or currency to display, or even the tagging parameters to collect search-related data to generate conversational search features and analytics.

Depending on whether you are retrieving static or dynamic configuration values in your snippet configuration, you define an object or a function to initialize Interface X:

• To retrieve static configuration values, define an initialization object as follows:

• To retrieve configuration values dynamically, use an initialization function:

NOTE:

You can change the snippet configuration values once the project is deployed. Use the /x-archetype/public/snippet-script.js file to perform hot changes for the snippet parameters. For more information on the supported parameters, check out Snippet configuration.

Loading the script

Once the snippet configuration is ready, add the Interface X script to your webpage. The script is hosted in a URL with the following syntax:

• Production: https://x.empathy.co/{INSTANCE}/app.js

• Staging: https://x.staging.empathy.co/{INSTANCE}/app.js

For example, to load the production version script for the instance my-store, you need to add the following scripts to your HTML:

In the case you want to load the script for the staging environment, you just modify the script attribute src so that it points to the staging environment as follows:

Thus, when the Interface X JavaScript file is loaded, it retrieves the configuration from the defined object or function.

Initializing the Interface X project on demand

On-demand initialization allows you to control when Interface X is loaded.

Steps to initialize the project on demand

1. Load the Interface X script.

2. Initialize Interface X.

Loading the script

Add the Interface X script hosted in a URL with the following syntax:

• Production: https://x.empathy.co/{INSTANCE}/app.js

• Staging: https://x.staging.empathy.co/{INSTANCE}/app.js

For example, to load the production version script for the instance my-store, you need to add the following script to your HTML:

<script src="https://x.empathy.co/my-store/app.js" type="module"></script>

In the case you want to load the script for the staging environment, you just modify the script attribute src so that it points to the staging environment as follows:

<script src="https://x.staging.empathy.co/my-store/app.js" type="module"></script>

Initializing Interface X

Since no initialization configuration is defined when loading the script, you need to invoke the initialization function created automatically in the X API (opens new window)object to provide the initialization options:

For this example, the initialization function is called immediately after loading the script, but it can be called at any time. Note that you need to call this function only once.