Guidelines for implementing Web Extend through Google Tag Manager

The purpose of this document is to give you some general guidelines and tips for the implementation of the Emarsys data-collection scripts (Web Extend) to your website, using your existing Google Tag Manager (GTM) setup.

For specifications and requirements regarding Web Extend implementation, please refer to the Web Extend JavaScript API documentation.

Important note: You will most probably need to extend your GTM implementation to fully serve Web Extend. You will need to declare new variables and create new tags – tasks that will require professional IT resources and a deep understanding of how your website is set up.

Contents

Introduction

Google Tag Manager provides a single code snippet, called the container code, that needs to be implemented on the website only once. Once implemented, users are able to add various code snippets and third-party vendor tags using a straightforward user interface available at https://tagmanager.google.com/.

However, even using a tag management system, the implementation of more complex functions often requires extra coding.

This coding involves creating or expanding the so called data layer. The data layer is a meta structure standardizing data formats and giving GTM an extra database to use while deploying advanced tags like the ones you will use for Web Extend.

Generic GTM data layer requirements

By default, GTM only sees the data (variables) that are present on the webpage. It is generally known that GTM can have difficulties capturing some of these variables properly: special text formatting (e.g. price values will be formatted with different currencies and number formatting) can make reading the data difficult, and also some data may not be present on every page by default (for example, Web Extend requires the website to report cart contents on every page, even where the content of a cart is not being listed by the webpage by default).

The solution to these difficulties is to pass such data to GTM by adding it to the data layer.

Technically the data layer is an array JavaScript object containing key-value pairs:

var dataLayer = dataLayer || [];
dataLayer.push({
  ‘visitorId’: 345,
  ‘visitorEmail’: ‘john@doe.tld’,
});

You can read more about the data layer and how and where it should be placed in your website’s source code in the detailed documentation of Google Tag Manager.

For a complete list of data required for your Web Extend integration, please see Annex 1.

Guidelines for integrating Web Extend

Generally speaking, it is highly recommended for website owners to implement the Enhanced Ecommerce data layer for Google Tag Manager. Although this involves a longer initial coding effort, as a result, GTM users are able to pass specific product data to several tag vendors, including Web Extend.

Note: In this guide we assume that Enhanced Ecommerce implementation is ready to be used and the required codes are placed above the GTM container code snippet as recommended by Google. In any other special cases you will need to adjust triggers and settings depending on your specific website functionality.

Please also note that Emarsys is not able to provide you with a detailed guide for all possible scenarios for website structure. If you have any specific questions, you should reach out to your agency support or a Google Analytics Certified Partner.**

Creating variables and tags containing Web Extend JavaScript

To support all the necessary elements of your Web Extend integration, first you will need to create several GTM variables:

  1. ecommerce – A data layer variable that will read your Enhanced Ecommerce data. This will be the source in your other variables and tags to pass product data to Web Extend:

web-extend-gtm-ecom.png

  1. Category path – You will need to include the category currently browsed by the visitor into the data layer; this has to be read into a GTM variable.
    NOTE: The category value passed to the ‘category’ Web Extend command needs to match exactly the category values included in the product catalog:

web-extend-gtm-category.png

  1. Cart content – As mentioned above, Enhanced Ecommerce does not include the contents of the cart on all pages, but this is required by Web Extend. Therefore, you will need to add this into the initial data layer declaration in the <head> tag yourself. There are no recommended naming conventions here; just make sure you include everything needed by the cart command (for example, item quantity and total price as well).

You may then read the data layer using a GTM variable and add this to the cart command. The cart command can be included in your general Emarsys tag described below.

Creating the Emarsys Tag

Once the variables are set up, you will need to create a new tag with the type “Custom HTML”. We will refer to this as the ‘Emarsys Tag’.

This Emarsys Tag will include JavaScript code (use the linked JSFiddle example to create your own code) containing all the commands required by the Web Extend API.

As you can see in the JSFiddle, the code first loads the Web Extend API itself. This must reference your Merchant ID, as issued by Emarsys.

Next, the code checks the page type that we are currently on.

Once that is determined, it is easy and straightforward to use your existing enhanced ecommerce implementation and call the correct Web Extend data-collection commands from the tag: view or category or purchase

web-extend-gtm-emarsystag.png

Use the JSFiddle sample code to create your own tag implementation!

Special considerations and options

User identification

The terms of services of GTM prohibit the use of personal information within Google tags. However, you can add such data into the data layer but have to ensure that such data does not get passed towards any Google tag, including your Google Analytics tags. But you can pass this to any third-party vendor like Emarsys to make sure the tracking of customers is working as expected.

The Web Extend API offers two methods to pass logged-in customer data:

  • Providing the ID of your user in your user database.
  • Providing the email address of this user.

Note: We recommend using the email address, since this means that you do not have to maintain an external ID. Either way, you will need to add this as a key in you initial data layer added in the <head> section of your website.

You will need to create a new GTM variable in your GTM container which loads this data from your data layer. We will take a GTM variable called User Email as an example. You can edit your general Emarsys tag mentioned above to also include the Web Extend command that sets the user email using this User Email variable name:

ScarabQueue.push(['setEmail', {{User Email}} ]);

Annnex 1. Summary Table of Data required for Web Extend implementation

The types of data you need to make available to Emarsys JavaScript are:

Type of data Description Web Extend command GTM source
User identifier Either your own internal userID, or the email address of the user. setEmail / setCustomerId Add to the initial data layer, e.g. User Email.
Product ID The unique identifier used to identify products, as recorded in your Google Product Feed or Emarsys product catalog .csv. view, cart, purchase Enhanced Ecommerce. For the cart command you have to add this as a separate data layer item on all pages of your website.
Category path The visited category path, as recorded in your Google Product Feed or Emarsys product catalog .csv. category Add to the initial data layer.
Product quantity When a product is added to a cart or purchased. cart,purchase Enhanced Ecommerce. For the cart command you have to add this as a separate data layer item on all pages of your website.
Product total price When a product is added to a cart or purchased (taking quantity and any discounts into account). cart,purchase Enhanced Ecommerce. For the cart command you have to add this as a separate data layer item on all pages of your website.