Data Layer Converter

[#1]

This article provides a solution for converting a non-Tealium data layer object into a format compatible with the Tealium Universal Data Object. It takes a nested data object such as digitalData (W3C) or dataLayer (Google Tag Manager) and flattens it to be an object of strings or arrays of strings, per the Tealium best practice.

The current solution: Version 1.3

In this article:

Table of Contents Placeholder

How It Works

There are different ways to implement a data layer on your website, some of which use nested objects and arrays. These formats can be helpful in representing complex data, but they don't work well with iQ Tag Management. iQ expects the data in utag_data to be flat, meaning only values of type strings, numbers, and arrays of strings/numbers. This solution allows you to keep a nested data layer object and convert it the flat format expected by iQ.

An example digitalData object with nested objects:

{
    "page": {
        "pageInfo": {
            "effectiveDate": "2015-10-01",
            "expiryDate": "2020-12-18",
            "language": "en-US",
            "publishDate": "2015-10-01",
            "publisher": "Company",
            "version": "v1.0",
            "pageHeader": "Lorem ipsum dolor sit amet, consectetur adipisicing elit",
            "description": "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua",
            "keywords": "TEST",
            "pageName": "Homepage"
        },
        "attribute": {
            "jQueryNativeVersion": "2.2.4"
        },
        "session": {
            "pageloadEpoch": 1488329663998,
            "uSessionID": "015a68b867ae0013994e512cb7a304078002307000c48-1488309121962",
            "uPageViewID": "6c595d7e22985ff86351edd694241cb7d0cf84a4195635b1d5392e1d31df1047"
        }
    },
    "user": {
        "userInfo": {
            "browser_lang": "en-us",
            "ipcinfo": "en-us",
            "signedin": false,
            "city": "del mar",
            "company_name": "tealium inc",
            "country": "us",
            "country_name": "united states",
            "employee_count": "n/a",
            "industry": "software & technology",
            "information_level": "detailed",
            "marketing_alias": "tealium",
            "phone": "858-779-1344",
            "registry_city": "san diego",
            "registry_country_code": "us",
            "registry_state": "ca",
            "state": "ca",
            "stock_ticker": "n/a",
            "sub_industry": "data & technical services",
            "web_site": "tealium.com"
        }
    }
}

The flattened Tealium utag_data object after conversion:

{
    "page.pageInfo.effectiveDate": "2015-10-01",
    "page.pageInfo.expiryDate": "2020-12-18",
    "page.pageInfo.language": "en-US",
    "page.pageInfo.publishDate": "2015-10-01",
    "page.pageInfo.publisher": "Company",
    "page.pageInfo.version": "v1.0",
    "page.pageInfo.pageHeader": "Lorem ipsum dolor sit amet, consectetur adipisicing elit",
    "page.pageInfo.description": "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua",
    "page.pageInfo.keywords": "TEST",
    "page.pageInfo.pageName": "Homepage",
    "page.attribute.jQueryNativeVersion": "2.2.4",
    "page.session.pageloadEpoch": "1488329663998",
    "page.session.uSessionID": "015a68b867ae0013994e512cb7a304078002307000c48-1488309121962",
    "page.session.uPageViewID": "6c595d7e22985ff86351edd694241cb7d0cf84a4195635b1d5392e1d31df1047",
    "user.userInfo.browser_lang": "en-us",
    "user.userInfo.ipcinfo": "en-us",
    "user.userInfo.signedin": "false",
    "user.userInfo.city": "del mar",
    "user.userInfo.company_name": "tealium inc",
    "user.userInfo.country": "us",
    "user.userInfo.country_name": "united states",
    "user.userInfo.employee_count": "n/a",
    "user.userInfo.industry": "software & technology",
    "user.userInfo.information_level": "detailed",
    "user.userInfo.marketing_alias": "tealium",
    "user.userInfo.phone": "619-555-1212",
    "user.userInfo.registry_city": "san diego",
    "user.userInfo.registry_country_code": "us",
    "user.userInfo.registry_state": "ca",
    "user.userInfo.state": "ca",
    "user.userInfo.stock_ticker": "n/a",
    "user.userInfo.sub_industry": "data & technical services",
    "user.userInfo.web_site": "tealium.com"
}

Configuration 

Adding this converter to your iQ profile requires pasting a large block of JavaScript code into an extension, then adjusting some of the code to accommodate your specific data layer conversion.

Add the Code

To set up the data layer converter:

1. Add a JavaScript Extension.
   
2. Title the extension "Data Layer Converter".
3. Set the scope to "Pre Loader".
4. Add the code from this file into the extension: https://tags.tiqcdn.com/utag/tealium-solutions/main/prod/utag.9.js

Utility Functions

The provided code allows you to modify the behavior of the converter using the following utility functions:

teal.ignore_keys

Specify the strings of text that if a key in the object starts with this text, that key will not be ingested.  An example object would be:

teal.ignore_keys = {
  "user" : 1,
  "util" : 1
};

This would result in all keys from the source data object to be skipped if they begin with the string "user" or "util".

teal.prefix

Set the string to use to prefix all key names that are converted.  If you're merging utag_data and dataLayer, you may want to notate the converted variables with the prefix of "dl_".  Using the dataLayer example from above, if you specify the prefix of "dl_" the output values woud look like this:

{
   "dl_user.userInfo.sub_industry" : "data & technical services",
   "dl_user.userInfo.web_site"     : "tealium.com"
}

teal.nested_delimiter

Set the character used to delimit the subkey names in the converted names. The default delimiter is a period, '.'.

teal.replace_keys

Specify new names for converted keys.  You can either replace a key name with a new name or simply remove the key altogether.

Examples:

The source object contains "pageInfo", which you want to appear as "pi" in the converted object eg. "digitalData.page.pageInfo.pageName" changes to "digitalData.page.pi.pageName"

teal.replace_keys = {
    "pageInfo" : "pi"
};

The source object contains "pageInfo", which you want to remove from the converted object eg. "digitalData.page.pageInfo.pageName" changes to "digitalData.page.pageName":

teal.replace_keys = {
    "pageInfo" : ""
}; 

Now that the data layer converter is installed in your profile you can make use of the functionality in two ways:

1. Convert the source data layer to utag_data once on page load
2. Convert the source data layer object on every tracking call

In most cases you will want to implement both options. 

Convert Page Data Layer

This is needed if you want to use your own data layer object with utag.js.

1. Add a JavaScript Code Extension
2. Title the extension, "Convert to utag_data".
3. Set the scope to "Pre Loader".
4. Add the following code:
   

   utag_data = teal.flattenObject(digitalData);

   Update digitalData to your actual data layer object name.

5. Ensure this extension is below the Data Layer Converter extension mentioned above.

Convert Data Layer on Tracking Calls

This is needed if you are passing your third-party data layer object to your Tealium tracking calls.

For example:

utag.link({
    "event" : {
        "type": "cart", 
        "name": "add to cart",
        "items" : [{
            "id": "prod123",
            "price": "123.45",
            "qty": "2"
        }]
    }
});

1. Add a JavaScript Code Extension
2. Title the extension "Convert Tracking Calls".
3. Set the scope to "All Tags".
   
4. Change the execution to "Before Load Rules".
   
5. Add the following code:
   

   teal.flattenObject(b,b);

Send a utag.link on dataLayer.push

There may be times when coding a utag.link is not feasible. In these cases you have the ability to redefine the Google Tag Manager dataLayer.push function and add a utag.link call with our flattened object.

If you are using this approach, you do not need this call to teal.flattenObject:

teal.flattenObject(b,b);

Instead, follow these steps:

1. Add a JavaScript Code Extension
2. Title the extension "Send utag.link on dataLayer.push".
3. Set the scope to "Pre Loader".
   
4. Add the following code:
   

   var tealPush = dataLayer.push;
   dataLayer.push = function() {
       var data = teal.flattenObject(arguments[0]);
       if (data.event 
           && data.event && data.event.indexOf("gtm.js") === -1
           && data.event.indexOf("gtm.dom") === -1
           && data.event.indexOf("gtm.load") === -1)
       {
           data.tealium_event = data.event;
           utag.link(data);
       }
       return tealPush.apply(this, arguments);
   };