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. 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 iQ Tag Management. iQ Tag Management 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": "858-779-1344",
    "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 account by pasting JavaScript code into an extension and then adjusting parts of the code to accommodate your specific data layer conversion.

The added functionality is used in one of the following methods (or both):

Convert Page Data Object
Convert the source data object to the Universal Data Object (utag_data) on every page load.
Convert Tracking Calls
Convert the source data object on every call to utag.view() and utag.link() .

Add the Code

The data layer converter code is attached as a JavaScript file to this article.

Use the following steps set up the data layer converter:

In the left sidebar, go to iQ Tag Management > Extensions.
Add a JavaScript Code extension.
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.
Open the JavaScript file attached to this article and copy it to your 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"

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 left 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 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 left 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 Tagsfrom 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.

Use with Google Tag Manager

This solution can also be used inside of Google Tag Manager (GTM) to convert the dataLayer, and tracked events. Read about setting up Tealium Collect in Google Tag Manager.