iQ Tag Management

1 Kudo

This article describes how to use the data layer converter as a solution for converting a non-Tealium data layer object into a format compatible with the Tealium Universal Data Object.

In this article:

Table of Contents Placeholder

How It Works

The data layer converter allows you to keep a nested data layer object and convert it to the flat format expected by iQ Tag Management (TiQ). The data layer converter takes a nested data object, such as digitalData (W3C) or dataLayer (Google Tag Manager), and flattens it into an object of strings or arrays of strings. 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 do not work well with TiQ. TiQ expects the data in utag_data to be flat, meaning that it contains only values of type strings, numbers, and arrays of strings or numbers.

Example: digitalData

The following example shows a digitalData object with nested objects before using the data layer converter:

{
    "page": {
        "pageInfo": {
            "effectiveDate": "2018-10-01",
            "expiryDate": "2020-12-18",
            "language": "en-US",
            "publishDate": "2018-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"
        }
    }
}

After using the data layer converter, the flattened Tealium utag_data object looks like this:

{
    "page.pageInfo.effectiveDate": "2018-10-01",
    "page.pageInfo.expiryDate": "2020-12-18",
    "page.pageInfo.language": "en-US",
    "page.pageInfo.publishDate": "2018-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

The data layer converter is added to your iQ profile by pasting a large block of JavaScript code into an extension and then adjusting parts of the code to accommodate your specific data layer conversion.

Add the Code

Use the following steps set up the data layer converter:

In the sidebar, go to iQ Tag Management > Extensions.
Add a JavaScript extension. (Learn More).
In the Title field, enter Data Layer Converter.
In the Scope field, select Pre Loader from the drop-down list.
In the Draft Name field, enter a name for your draft.
Go to https://tags.tiqcdn.com/utag/tealium-solutions/main/prod/utag.9.js and copy the code to the clipboard.
Paste the copied code into the JavaScript field for the extension.
Click Approve for Publish.
Select one or more publish environments and click Apply.

The planned publish environments now display.
Save and publish your changes.

Utility Functions

The code provided 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.
Example Object:
```
teal.ignore_keys = {
  "user" : 1,
  "util" : 1
};
```
This action will result in all keys from the source data object being 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 are merging utag_data and dataLayer, you can note that the converted variables contain a prefix of "dl_". Using the dataLayer example from above, if you specify the prefix of "dl_", the output value results are as follows:
```
{
   "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 the period character (.).
teal.replace_keys
Specify new names for converted keys. You can either replace a key name with a new name or remove the key altogether.
Example:
```
teal.replace_keys = {
    "pageInfo" : ""
}; 
```
The source object contains "pageInfo", which you want to appear as "pi" in the converted object, for example, "digitalData.page.pageInfo.pageName" changes to "digitalData.page.pi.pageName"

Using the Installed Functionality

Now that the data layer converter is installed in your profile, you can make use of the functionality using one of the following methods. In most cases, you will want to implement both options.

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

Convert Page Data Layer

Use convert page data layer if you want to use your own data layer object with utag.js.

Use the following steps to add a this extension:

In the sidebar, go to iQ Tag Management > Extensions.
Add a JavaScript extension. (Learn More).
In the Title field, enter Convert to utag_data.
In the Scope field, select Pre Loaderfrom the drop-down list.
In the Draft Name field, enter a name for your draft.
Copy and paste the following code into the JavaScript field for the extension:
```
utag_data = teal.flattenObject(digitalData);
```
Update digitalData to your actual data layer object name.
Ensure that this extension is listed below the Data Layer Converter extension created in the previous step.
Click Approve for Publish.
Select one or more publish environments and click Apply.
The planned publish environments now display.
Save and publish your changes.

Convert Data Layer on Tracking Calls

You must convert data layer on tracking calls if you are passing your third-party data layer object to your Tealium tracking calls.

Example:

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

Use the following steps to convert data layer tracking calls:

In the sidebar, go to iQ Tag Management > Extensions.
Add a JavaScript extension. (Learn More).
In the Title field, enter Convert Tracking Calls.
In the Draft Name field, enter a name for your draft.
In the Scope field, select All Tags from the drop-down list.
Change the execution to Before Load Rules.
Copy and paste the following code into the JavaScript field for the extension:
```
teal.flattenObject(b,b);
```
Click Approve for Publish.
Select one or more publish environments and click Apply.
The planned publish environments now display.
Save and publish your changes.

Send a utag.link on dataLayer.push

When coding a utag.link is not feasible, you can redefine the Google Tag Manager dataLayer.push function and add a utag.link call with the Tealium flattened object.

When using this approach, you do not need to use the following command call to teal.flattenObject:

teal.flattenObject(b,b);

Use the following steps instead:

In the sidebar, go to iQ Tag Management > Extensions.
Add a JavaScript extension. (Learn More).
In the Title field, enter Send utag.link on dataLayer.push.
In the Draft Name field, enter a name for your draft.
In the Scope field, select Pre Loader from the drop-down list.

Copy and paste the following code into the JavaScript field for the extension:

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);
};

Click Approve for Publish.
Select one or more publish environments and click Apply.
The planned publish environments now display.
Save and publish your changes.