Data Layer Enrichment

Data Layer Enrichment

by on ‎06-15-2015 09:39 AM - edited on ‎07-27-2018 03:06 PM by Community Manager (8,531 Views)

Data Layer Enrichment makes AudienceStream visit and visitor attributes available in your Tealium iQ configuration and populates that data in your data layer.

In this article:

Table of Contents Placeholder

What is Data Layer Enrichment?

Data Layer Enrichment imports your AudienceStream attributes into your Tealium iQ account and makes them available as part of your data layer. The customer data collected in AudienceStream is populated in the data layer on your website. Those attributes can then be used in load rules, extensions, and tags in your iQ account to create personalized experiences for your customers. 

How It Works

Data Layer Enrichment is a profile-level setting in iQ that links to a corresponding AudienceStream profile. Once enabled, a new type of data layer variable called "AudienceStream Attribute" will appear in the list of variables on the Data Layer screen. The visit and visitor attributes from the AudienceStream profile will be imported and become available to use just like any other data layer variable.

dle-as-attributes.png

These attributes are populated with real-time customer data into the Universal Data Object (UDO) using the Tealium Collect Tag.

Upon a visitor's first visit (and first page view) to your site the Tealium Collect tag sends a call to AudienceStream to retrieve the most recent visitor profile attributes. The data is place in the browser's local storage for future use.

On the second page view, the AudienceStream attributes are now in your UDO and will affect any load rules, extensions, or tags that are configured with them.

Because tags load asynchronously, the most recently retrieved set of attributes will be available for use on subsequent page and event tracking, rather than on the current page's events.

Same Origin Policy

It's important to note that the browser mechanism used to store customer data, localStorage, adheres to the same origin policy for security purposes. This means that data layer enrichment does not persist across http protocols or subdomains.

For example, when going from a page on "www.tealium.com" to a page on "secure.tealium.com", the data layer enrichment data stored in localStorage will not persist to the new subdomain. Therefore, when a user changes subdomains or protocols a new data layer enrichment call must be made to re-populate localStorage and the data may not be available until the subsequent page view.

Prerequisites

These are the requirements for using data layer enrichment:

  • AudienceStream - You need an active AudienceStream account with visit and visitor attributes defined. If you do not have an AudienceStream account, contact your account manager.
  • Data Layer Enrichment enabled in iQ - Contact your account manager to enable your account to take advantage of Data Layer Enrichment.
  • Tealium Collect tag - You need to add the Tealium Collect tag to your Tealium iQ profile.
  • Latest version of utag.js - You need utag.js version 4.27 or later.
    Learn how to update your utag.js version.

Enabling Data Layer Enrichment

To enable data layer enrichment you must select an AudienceStream profile from which to import the attributes. By default, Tealium iQ will load attributes from the "main" AudienceStream profile, but an alternative profile can be set in the Publish Configuration area of iQ.

 To set the AudienceStream profile used for data layer enrichment:

  1. In Tealium iQ, click Save/Publish.
  2. Click Configure Publish Settings... in the upper-right of the modal.
  3. On the General Publishing tab, scroll to the bottom of the Implementation section.
  4. Select the appropriate Data Layer Enrichment Profile.
  5. Click Apply and continue to save and publish your changes to the Prod environment.

dle-profile-setting.png

Adding and Configuring the Tealium Collect Tag

For detailed instructions see the Tealium Collect Tag Setup Guide.  Tealium-Collect-Most-Common-Settings.jpg

Data Enrichment Frequency

To set up your Tealium Collect tag to enable Data Layer Enrichment, you must determine how often you will update your data layer with attribute information. Here are the options:

  • None: (default) Data layer enrichment will not occur.
  • Infrequent: Data layer enrichment occurs once per visit (session). The retrieved customer data is stored in local storage for use on subsequent page views during the session. 
  • Frequent: (recommended) Data layer enrichment occurs on every page view. This allows for customer data that changes during the session to be refllected in real-time in the UDO.

    This option causes an additional HTTP request per page.

Selecting a Load Rule 

We recommend leaving the default 'Load on All Pages' load rule selected for the Tealium Collect tag. In order to make your data layer as rich and robust as possible, you need to populate it with the most relevant data as soon as you can.

Using AudienceStream Attributes in Tealium iQ 

AudienceStream attributes are treated as imported variables in Tealium iQ. This means you cannot edit or delete them from Tealium iQ. If you want to delete or modify an AudienceStream attribute, you must do so from your AudienceStream profile. Moreover, you cannot import attributes to a profile library, only to a regular profile. 

dle-iq-as-variables.png

Which AudienceStream attribute types are imported?

Not all data types are imported into your iQ account. The following data types will be imported and made available in iQ:

  • Badges
  • Numbers
  • Strings
  • Booleans
  • Dates 

Building Load Rules

You can use the attributes to create your load rules. Two new rule operators are available to accommodate the use of badges in load rules. 

  • is badge assigned
    True if the badge attribute is assigned to the visitor.
  • is badge not assigned
    False if the badge attribute is not assigned to the visitor.

dle-badge-is-assigned.png

Deleting an attribute from AudienceStream automatically removes it from the data layer screen in iQ as well. However, load rules that use a deleted attribute do not automatically remove it from their logic. You must manually update load rules that still reference deleted AudienceStream attributes.

Callback Function

The data layer enrichment request provides a callback mechanism so that you can execute code based on the response of the data layer enrichment request. There is a callback method named window.tealium_enrichment() .

To use the callback function create a JavaScript Code extension scoped to Pre Loader with the following code example: 

window.tealium_enrichment = function(data) {
console.log("Data Layer Enrichment Callback");
// Your code here...
}; 

Data Layer Enrichment Object

The data object returned in the callback has the following properties that correspond back to the AudienceStream attributes:

DLE Property Description
audiences

Audiences

Object containing key/value pairs for each audience the user is in, where the key is ACCOUNT_PROFILE_ID and the value is the name of the audience.

Example:

audiences: {
    "tealium_main_208" : "Mobile User",
"tealium_main_209" : "DV Attendee"
}
badges

Badges

Object containing key/value pairs for each badge assigned to the user, where the key is BADGE-ID and the value is true.

Example:

badges: {
    30: true,
    128: true,
    323: true
}

 

current_visit

Visit Attributes

Object containing all the relevant visit-scoped attributes.

Example:

current_visit: {
    dates: { ... },
    flags: { ... }, // boolean attributes
    metrics: { ... }, // number attributes
    properties: { ... }, // string attributes
    property_sets: { ... } // set of string attributes
}
dates

Dates

Object containing key/value pairs where the key is the attribute ID of the data attribute or an audience ID in the form of audience_account_profile_id_count_ts and the value is a unix timestamp.

Example:

dates: {
    9356: 1491233145706,
    audience_tealium_main_103_count_ts: 1532722471000
}
flags

Booleans

Object containing key/value pairs for each boolean attribute, where the key is BOOLEAN-ID and the value is true or false.

Example:

flags: {
    530: true,
    6128: false
}
metric_sets

Tallies

Object containing sub-object representing tally attributes where the keys are the ID of the attribute and the value is an object with the contents of the tally.

Example:

metric_sets: {
    57: {
        Chrome: 2470,
        Firefox: 9,
        Safari: 10
    }
}
properties

Strings

Object containing key/value pairs where the keys are the ID's of string attributes and the values are the stored values.

Example:

properties: {
    9921"United States",
    9923"tealium.com"
}
property_sets

Set of Strings

Object containing key/value pairs where the key is the ID of the attribute and the value is an array of the stored unique values.

Example:

property_sets: {
    7604: ["Social", "Display", "DMP", "CRM"],
    7606: ["Personalization", "Analytics", "Email"]
}