The purpose of this document is to give you some general guidelines and tips for the implementation of the Emarsys data-collection API scripts to your website, using your existing Google Tag Manager (GTM) setup.
For specifications and requirements regarding this implementation, please refer to the Data collection JavaScript API documentation.
You will most probably need to extend your GTM implementation to fully serve our data collection scripts. 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 data collection.
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, we require 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 integration, please see the summary table below.
Guidelines for integrating the JavaScript API
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 Emarsys.
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 the Emarsys JavaScript
To support all the necessary elements of your integration, first you will need to create several GTM variables:
- 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 Emarsys:
2. 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.
The category value passed to the ‘category’ JavaScript command needs to match exactly the category values included in the product catalog:
3. Cart content – As mentioned above, Enhanced Ecommerce does not include the contents of the cart on all pages, but this is required by Emarsys. 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 data collection API.
As you can see in the JSFiddle, the code first loads the data collection 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 e-commerce implementation and call the correct data-collection commands from the tag: view or category or purchase
Use the JSFiddle sample code to create your own tag implementation:
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 data collection 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 JavaScript command that sets the user email using this User Email variable name:
ScarabQueue.push(['setEmail', {{User Email}} ]);
Summary table of data required for implementation
The types of data you need to make available to Emarsys JavaScript are:
| Type of data | Description | JavaScript 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. |