About Hosted Data Layer

[#1]

Hosted data layer facilitates the use of statically hosted data for the purpose of supplementing the dynamic on-page data layer of your website. 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. This article provides a feature overview and a description of the components required for a full implementation of hosted data layer.

This article covers the following topics:

Table of Contents Placeholder

How It Works

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 (2) required components, the Hosted Data Layer API and 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.

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. The extension fetches the hosted data layer objects and combines the contents of each object with the on-page data layer 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 will be 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 hosted data layer process begins when utag.js loads on the page. The hosted data layer extension runs in the "All Tags" scope, executed "Before Load Rules". When it runs it 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.

In summary:

1. The Hosted Data Layer API is used to upload JSON data files to the CDN.
2. The Hosted Data Layer extension is configured in iQ with identified lookup variables.
3. utag.js 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.

• 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:

1. 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.
   
   
2. 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 containing the value of product_id is created for every product.
   
   
3. 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 variables determine 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"] })