Customer Data Hub

This article describes how to set up Tealium Collect in Google Tag Manager (GTM).

Tealium Collect is available as a custom tag template in Google Tag Manager. See Install Tealium Collect for Google Tag Manager.

This solution includes uses the GTM data layer helper, the Tealium data layer converter, and custom extensions to put it all together. In the end you will have the Universal Tag (utag.js) running in GTM and events being tracked by Tealium Collect.

In this article:

Table of Contents Placeholder

How It Works

To run Tealium Collect in GTM you have to add a message listener to Google's dataLayer queue and convert GTM event data into a format expected by the Universal Tag (utag.js). This requires configuration in both Tealium iQ Tag Management and Google Tag Manager. When the solution is in place, Tealium Collect will have the ability to track all of the events flowing through your GTM implementation. Events will be received in Tealium EventStream for processing server-side.

In iQ Tag Management you will:

Add the Tealium Collect tag
Add JavaScript Code extensions to do the following:
- Suppress default page tracking
- Load the Google Data Layer Helper
- Load the Tealium Data Layer Converter (flattener)
- Add a message listener to pass GTM events to utag.view and utag.link

In Google Tag Manager you will:

Add the Universal Tag (utag.js) as a custom HTML tag

In EventStream you will:

Add event attributes with names matching the converted variables from the dataLayer

Configure Tealium iQ Tag Management

In your iQ Tag Management account you will add the Tealium Collect tag and several JavaScript Code extensions to integrate with the GTM dataLayer queue.

Add the Tealium Collect Tag

Add the Tealium Collect tag. Then, under Advanced Settings, enable the Bundle Flag. This will build the Tealium Collect tag code into utag.js so that only one JavaScript file is loaded.

References:

Add Extensions

The following JavaScript Code extensions must run in the scope and order specified.

Reference: JavaScript Code Extension

1. Suppress Default Page Tracking

When the Universal Tag is loaded on a page, it defaults to tracking that page view with the utag_data object defined in the page code. However, when loading the Universal Tag in GTM, this default behavior must be suppressed so that tracking calls will only originate from the GTM event listener.

Extension: JavaScript Code
Scope: Pre Loader
Code:

 /**
 * Scope       : Pre Loader
 * Execution   : n/a
 * Condition   : n/a
 * Description : Disable automatic utag.view() event that fires on page load.
 */

// disable the automatic view, we want to fire it from the listener instead
// Doc: https://docs.tealium.com/platforms/javascript/settings/
window.utag_cfg_ovrd = window.utag_cfg_ovrd || {};
window.utag_cfg_ovrd.noview = true;

2. Google Data Layer Helper

Add the Google Data Layer Help script. This allows you to add a listener to the dataLayer message queue so that all GTM events can also be tracked as Tealium events. This code adds the constructor new DataLayerHelper() that allows you to add a listener function to GTM events.

Extension: JavaScript Code
Scope: DOM Ready
Code: Copy from https://raw.githubusercontent.com/google/data-layer-helper/master/dist/data-layer-helper.js

Reference: Google Data Layer Helper

3. Tealium Data Layer Converter

Use the data layer converter code to provide a JavaScript utility to convert GTM data objects into the format expected by the Universal Tag. This code adds the method teal.flattenObject(), which converts the GTM event into a data object for use with utag.view and utag.link .

Extension: JavaScript Code
Scope: DOM Ready
Code: Copy code from Reference article below

Reference: Tealium Data Layer Converter

4. GTM Event Listener

This extension brings all the components together to make it work. The data layer helper is used to add a listener function to GTM events and the data layer converter creates an event data object that can be passed to utag.view() and utag.link() .

To control which events Tealium Collect should track either add additional logic to the JavaScript code or add a load rule to the tag.

Extension: JavaScript Code
Scope: DOM Ready
Code:

/**
 * Scope       : DOM Ready (run once)
 * Execution   : n/a
 * Condition   : n/a
 * Description : GTM Listener - Attach listener function using the DataLayer Helper
 */
 
// define listener function, will be called for each element in the dataLayer array
var processEvent = function(model, message) {
    // exit if the flattener function isn't present on the page
    if (!teal || typeof teal.flattenObject !== "function") {
        return;
    }

    /**
     * Process the model, once per page on (or after) DOM Load
     */
    var flat = {};
    
    // utag.view on gtm.load to ensure GTM and iQ timing matches, assumes non-SPA
    // processes the 'model', built by the helper based on all past events on the page
    if (message.event === "gtm.load") {
        //console.log(teal.flattenObject(message, message));
        flat = teal.flattenObject(model, model);
        flat.tealium_event = flat.page_type || flat.pageType || "other-view";
        utag.DB("View / " + flat.tealium_event, flat);
        utag.view(flat);
    }
    
    // some click events as examples (processes 'message' instead of 'model')
    if (message.event === "ButtonClickEvent" || message.event === "GAevent") {
        flat = teal.flattenObject(message, message);
        flat.tealium_event = flat.event;
        utag.DB("Link / " + flat.tealium_event, flat);
        utag.link(flat);
    }
};

// make sure the object is actually defined
window.dataLayer = window.dataLayer || [];

// attach the listener (and process any historical events on attachment)
if (typeof processEvent === "function") {
    var helper = new DataLayerHelper(window.dataLayer, processEvent, true);
};

Configure Google Tag Manager

Follow these steps to add a custom HTML tag in GTM to load the Tealium Universal Tag (utag.js).

From your GTM Workspace, click Add a New Tag.
Name the tag Tealium Collect.
Click Tag Configuration and select Custom HTML.

Copy and paste the following code into the HTML window.
Replace ACCOUNT and PROFILE with your Tealium iQ account and profile names.

<script type="text/javascript">
  (function(a,b,c,d){
  a='https://tags.tiqcdn.com/utag/ACCOUNT/PROFILE/prod/utag.js';
  b=document;c='script';d=b.createElement(c);d.src=a;d.type='text/java'+c;d.async=true;
  a=b.getElementsByTagName(c)[0];a.parentNode.insertBefore(d,a);
  })();
</script>

Set Tag firing options to Once per page.
Click Triggering and select All Pages.
Click Save.

Reference: Google Tag Manager: Custom HTML tag

Configure Tealium EventStream

In EventStream, use Live Events to inspect incoming events and create event attributes for the data coming from GTM.

Reference: Using Attributes