Data Layer Enrichment Public API

Data Layer Enrichment Public API

by on ‎06-05-2015 03:22 PM - edited on ‎04-26-2017 06:16 AM by (3,317 Views)

Data Layer Enrichment API allows you to retrieve a visitor profile, and its Universal Data Hub profile definition, for a known visitor ID, while that visitor has an active visit. By default, Data Layer Enrichment uses the visitor ID from the 3rd-party TAPID Cookie. If the TAPID cookie is disabled, it'll use the vistor ID from the URL path.

This article will walk you through the following:

Table of Contents Placeholder

Retrieving a Visitor Profile

To retrieve a visitor profile, use:

 GET http(s)://visitor-service.tealiumiq.com/{account}/{profile}/{visitor_id}

The above call will return the visitor profile JSON that looks something like this:

   {
        "metrics" : {
            "5117" : 6.0,
            "22" : 6.0
        },
        "dates" : { 
            "5111" : 1420223771043
        },
        "properties" : { 
            "17" : "http://tags.tiqcdn.com/utag/acct/prof/env/mobile.html", 
            "account" : "tealiummobile",
            "5123" : "set",
            "profile" : "demo"
        },
        "flags" : { "5115" : true } ,
        "current_visit" : {
            "metrics" : {
                "7" : 6.0
            },
            "dates" : {
                "5202" : 1420225387000
            },
            "properties" : {
                "48" : "Chrome",
                "45" : "Mac OS X",
                "44" : "Chrome",
                "47" : "browser",
                "46" : "Mac desktop"
            },
            "flags" : { }
        },
        "badges" : { "5113" : true },
        "audiences" : {
            "tealiummobile_demo_101" : "Sample Audience"
        }
    }

 

If the supplied visitor id is invalid, or if the visitor does not currently have an active visit, the API will return status code 200 and an empty json.

  

The returned visitor profile differs from the typical visitor profile in the following ways:

  • Badges and Audiences are transformed from an array to a map
  • Timelines and Funnels have been removed

If AudienceStream has not finished processing the AudienceStream request, meaning the visitor profile is not yet available at the time of the Data Layer Enrichment request, then an empty JSON will be returned.

There is a Data Layer Enrichment service that handles all enrichment requests. The visitor profile is stored and delivered from this service and updated every 5 seconds.

Retrieving a Universal Data Hub (UDH) Profile Definition

The returned visitor profile contains attribute IDs (e.g. metrics 5117). If you want the Data Layer to display something more meaningful to the end user, you can retrieve the UDH Profile Definition and translate the attribute IDs into attribute names.

To retrieve a UDH profile definition, use:

    GET http(s)://visitor-service.tealiumiq.com/datacloudprofiledefinitions/{account}/{profile}/{visitor_id}

This will return:

    {
        "audiences" : [
            {
                "id" : "tealiummobile_demo_101",
                "name" : "Sample Audience"
            }
        ],
        "badges" : [
            {
                "id" : 5113,
                "name" : "Sample Badge"
            },
            {
                "id" : 32,
                "name" : "Unbadged"
            },
            {
                "id" : 31,
                "name" : "Frequent visitor"
            },
            {
                "id" : 30,
                "name" : "Fan"
            }
        ]
    }

Currently, only audience and badge definitions are returned.

 

Whitelisting Domains

By default, Data Layer Enrichment honors requests from all domains. If you want to limit these requests from specific domains only, you must whitelist them in your Universal Data Hub (UDH) profile. The idea behind whitelisting is to prevent non-trusted domains from accessing visitor information in the TAPID cookie. When a visitor navigates to any domain outside the whitelist, that is potentially malicious, Data Layer Enrichment will stick to the visitor ID in the url path.

To create the whitelist,

  1. Navigate to your UDH profile.
  2. Drop down the gear icon at the top right and select Data Layer Enrichment.
  3. Enter the comma separated list of domains you trust. Do Not insert http/https protocol before the domain.
  4. Click Save. Then perform a Save-Publish.

You can add a maximum of 250 domains per profile.

When you whitelist a domain, all of its sub-domains are automatically included. For example, if you whitelist example.com, any sub-domain that matches *.example.com will be included.

Here are a few examples of referrers that match the subdomain criteria:

 http://example.com
 https://mobile.example.com/xyz/index.html
 http://app.mobile.example.com

How it works

The first thing Data Layer Enrichment does when it receives a request is check if there's a whitelist in your UDH profile.

If a whitelist is available, Data Layer Enrichment will attempt to match the referrer with the whitelisted domain(s).

  • If they match, Data Layer Enrichment will grab the visitor id from the 3rd-party TAPID cookie. 
  • If the match fails, Data Layer will grab the visitor ID from the url path. 

If a whitelist is not available, Data Layer Enrichment will use the visitor ID in the url path. 

In a nutshell

  • TAPID cookie is used when the referrer matches the whitelisted domain. 
  • The visitor ID from the url path is used when the referrer does not match the whitelisted domain or otherwise the TAPID cookie is disabled.

Use Case

A simple use case for using this would be a CMS that wants to enable next page personalization. Here are the steps to complete.

 

1) At a given internal, say once per hour, an automated script should run in the CMS that triggers the UDH Profile Definition API to pull in which Audiences and Badges could potentially be assigned to a visitor. This will be stored within the CMS and continually referenced in the following steps.

 

2) A script should exist in the CMS that runs the following code to capture the visitor's ID. This should run on page load and only if the CMS does not already have the visitor ID. This code pulls the value of the v_id key from the utag_main cookie namespace, a.k.a utag.data["cp.utag_main_vi_id"].

document.cookie.match(/v_id:([^$]+)/)[1]

3) The account and profile refer to the AudienceStream account and profile. This is important because many clients have a TiQ profile that differs from an AS profile. For example, the TiQ profiles tealium/audiencestream and tealium/tiq may point to the AS profile tealium/main.

 

4) You can now trigger the Visitor Profile API.

 

5) With the response of the Visitor Profile API, you can cross-reference against the response of the UDH Profile Definition API to see the names of which Audiences and Badges are assigned to the specific visitor.

 

What this will allow is, for example, on page 8 the visitor is assigned the "Sample Badge" in AudienceStream. On page 9, prior to page rendering the CMS will trigger a call to the Visitor Profile API and capture the latest profile for next page personalization.