iQ Tag Management

This article provides a feature overview and a description of the components required for a full implementation of hosted data layer.

In this article:

Table of Contents Placeholder

How It Works

Hosted data layer facilitates the use of statically hosted data for the purpose of supplementing the dynamic on-page data layer of your website or for hosting JSON configuration files. Although the data layer implemented on your website is useful in capturing real-time information, it can be a challenge to build out your data layer to contain all the data with value to your organization. Hosted data layer provides a convenient mechanism to upload your static data to the Tealium mCDN, from where it can be accessed by your web pages to enrich the on-page data or power an application that uses JSON files.

Data Layer Objects

Hosted data layer utilizes micro data layer objects that are associated to a variable in your on-page data layer. The hosted data layer object is a text file that contains a JSON object in which the key/value pairs represent the micro data layer. This file is uploaded to the CDN using the Hosted Data Layer API. The on-page data layer contains lookup variables, which are configured in the Hosted Data Layer extension in iQ, that are used to determine which hosted data layer object to fetch from the CDN.

The following sections provide a description of the two required components, the Hosted Data Layer API and the Hosted Data Layer extension.

These objects can also be plain JSON files used for purposes other than data layer augmentation and would not require the use of the Hosted Data Layer extension.

Hosted Data Layer API

The hosted data layer API allows you to upload the supplemental data to the CDN in a flat JSON object called a hosted data layer object. The API enables the programmatic processing of large amounts of data to be used as hosted data layer objects.

The following example shows the contents of a hosted data layer object:

{
    "product_category"           : ["Accessories"],
    "product_brand"              : ["Acme"],
    "product_sku"                : ["GEN-PRD-BLU"],
    "product_has_free_shipping"  : ["0"],
    "product_has_instore_pickup" : ["1"]
}

As shown in the example, a hosted data layer object looks similar to the data layer object on your website. While the on-page data layer describes the page and customer interactions, the hosted data layer object provides additional attributes based on a specific variable on the page. Additional attributes for a specific product are provided in the example.

The API can be used to store other types of information in JSON format, not only data layer values.

For detailed instructions, see How to use the Hosted Data Layer API.

Hosted Data Layer Extension

The hosted data layer extension is the component that combines the hosted data with the in-page data, as follows:

The extension fetches the hosted data layer objects and combines the contents of each object with the on-page data layer.
The extesnion then triggers a tracking call with the merged object.
The extension is configured to identify the data layer variables, also known as lookup variables, that are used to determine which hosted data layer objects are fetched from the CDN.

For detailed instructions, see How to set up the Hosted Data Layer extension.

Lookup Variable

A lookup variable identifies which variable in the on-page data layer will be used to fetch the corresponding hosted data layer object for that page. The lookup variable is the shared link between the hosted data layer objects and the hosted data layer extension.

You must identify your lookup variables first and then use the expected values of each variable to name your hosted data layer objects. For example, if your lookup variable is item_id and one of the values is 123, the corresponding hosted data layer object will be named 123.js.

Order of Operations

The following list summarizes the order of operations for the hosted data layer extension:

The hosted data layer process begins when utag.js loads on the page.
The hosted data layer extension runs in the All Tags scope, which is executed Before Load Rules.
When the hosted data layer extension runs and delays page tracking by setting utag.cfg.noview=true.
to ensure that no tags, load rules, or other extensions are evaluated until the hosted data is retrieved.
While the extension is running, the lookup variables are identified and each of their values is used to fetch the matching hosted data layer object from the CDN.
If a hosted data layer object is found, the data from that object is combined with the on-page data layer into a temporary object.
After all lookup variables are processed and a new data layer object is finalized, the extension triggers utag.view() with that new object.

Timing Issue
Due to the delay introduced by the hosted data layer extension, extensions scoped to "DOM Ready" might run before some "All Tags" extensions.

Summary Diagram

The following list and diagram summarizes how the hosted data layer extension processes data.

The Hosted Data Layer API is used to upload JSON data files to the CDN.
The Hosted Data Layer extension is configured with identified lookup variables in TiQ.
The utag.js script combines the on-page data layer with the fetched hosted data layer objects and calls utag.view().

Use Case: Supplementing Product Data

The following is a use case to illustrate how Hosted Data Layer can be used to add new data layer variables to the page.

You have a database of information for the products you sell on your website.
The basic product attributes, such as "ID", "Price", and "Name", are readily available to your web application and currently populated in the data layer on your page.
An offline system that is not available to your web application contains additional product attributes that you want to add to the on-page data layer, such as "SKU", "In Store Availability", "Free Shipping Status", and "Brand".

The following steps describe the implementation process for this use case:

Identify Lookup Variables
The on-page data layer contains product_id, which is also an identifier in the offline data and a good candidate for a lookup variable.
Create/Upload Hosted Data Layer Objects
A program is created to export the offline product data into JSON data files, which are named according to the expected values of product_id.
For example, if the on-page data layer contains product_id=["PRD123"] , then a matching Hosted Data Layer file named PRD123.js is created.
A separate file is created for every product.

Configure Hosted Data Layer Extension
With the lookup variable identified and hosted data layer objects uploaded, the Hosted Data Layer extension is then added and configured to use product_id.
Although your on-page data layer may only have product_id available, you have used the Hosted Data Layer API to upload additional product data. The lookup variable is now product_id, which means that the values of the product identifier variable determines the names of the hosted data layer objects.
The following table shows the end result of applying the enrichment process.

On-Page Data Layer

utag_data

{
    "page_type"  : "product",
    "product_id" : ["PRD123"]
}

Hosted Data Layer Object

PRD123.js

{
    "has_free_shipping"  : ["0"],
    "has_instore_pickup" : ["1"]
}

Merged Data Layer

(sent directly to utag.view())

utag.view({
    "page_type"          : "product",
    "product_id"         : ["PRD123"]
    "has_free_shipping"  : ["0"],
    "has_instore_pickup" : ["1"]
})

Use Case: AMP Analytics Remote Configuration File

This section illustrates a use case that shows how Hosted Data Layer can be used to serve a remote JSON configuration file for an implementation of AMP Analytics.

Prerequisites

An AMP site where you want to run certain tags

Serve a Remote JSON File to AMP Analytics

Use the following steps to serve a remote JSON file for an AMP Analytics configuration:

Identify your AMP Configuration
The amp-analytics configuration is specific to your vendor or event tracking needs.
For additional information, see the AMP Analytics documentation.
AMP Analytics JSON configuration example:

{
  "requests": {
    "pageview": "https://example.com/analytics?url=${canonicalUrl}&title=${title}&acct=${account}"
  },
  "vars": {
    "account": "A0123456789"
  },
  "triggers": {
    "trackPageview": {
      "on": "visible",
      "request": "pageview"
    },
    "links": {
      "on": "click", 
      "selector": ".tracked-links-selector", 
      "request": "event" 
    }
  }
}

Upload Hosted Data LayerJSON File
Your AMP configuration file can have any name, for example amp.analytics.config.json. In this use case, the data layer ID for the uploaded file is amp.analytics.config. Once the file is uploaded using the Hosted Data Layer API, it will then be available at the following location:
```
https://tags.tiqcdn.com/dle/{account}/{profile}/amp.analytics.config.json
```
Tag Your AMP Page
The new Hosted Data Layer JSON file can be referenced in your AMP pages using the amp-analytics tag, as shown in the following example
Example:
```
<amp-analytics config="https://tags.tiqcdn.com/dle/{account}/{profile}/amp.analytics.config.json">
```