Data Layer Enrichment Public API

[#1]

The Data Layer Enrichment Public API allows you to retrieve a visitor profile, and its Customer 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 third-party TAPID Cookie. If the TAPID cookie is disabled, it will use the Visitor ID from the URL path.

This article will walk you through the following:

Table of Contents Placeholder

Retrieving a Visitor Profile

Use the following GET command to retrieve a visitor profile:

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

The above command returns the visitor profile JSON similar to the following example:

   {
        "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 is returned.

A Data Layer Enrichment service handles all enrichment requests. The visitor profile is stored and delivered from this service and updated every five (5) seconds.

Retrieving a Customer Data Hub Profile Definition

The returned visitor profile contains attribute IDs, such as metrics 5117. If you want the data layer to display something more meaningful to the end user, you can retrieve the Customer Data Hub profile definition and translate the attribute IDs into attribute names.

Use the following GET command to retrieve a Customer Data Hub profile definition:

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

The above command returns the following:

    {
        "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"
            }
        ]
    }

In this example, only audience and badge definitions are returned. You can optionally append the   visitor_id parameter to the previous example. If this method is used, the response will be empty unless the specified visitor is currently active.

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 Customer Data Hub 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.

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

Use the following steps to create the whitelist:

1. Navigate to your Customer Data Hub profile.
2. From the gear icon in the top right of the screen, select Data Layer Enrichment from the drop-down list.
3. Enter the comma-separated list of domains you trust. You can add a maximum of 250 domains per profile.
   Do Not insert the http/ https protocol before the domain.
4. Click Save.
5. Click Save/Publish to save and publish your changes.

How it Works

The first thing Data Layer Enrichment does when it receives a request is to check if there is a whitelist in your Customer Data Hub profile. If a whitelist is available, Data Layer Enrichment attempts to match the referrer with the whitelisted domains.

The following list describes potential findings and results:

• No whitelist found
  If there is no whitelist is not available, Data Layer Enrichment uses the Visitor ID in the URL path. 
• Whitelist found, domains match
  If the referrer and the whitelisted domains match, Data Layer Enrichment gets the Visitor ID from the third-party TAPID cookie. 
• Whitelist found, domains do not Match
  If the referrer and the whitelisted domains do not match, Data Layer gets the Visitor ID from the URL path. 

In summary, the 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; otherwise the TAPID cookie is disabled.

Use Case

This section describes a simple use case in which a CMS wants to enable next page personalization.

At a given internal, for example once per hour, an automated script should run in the CMS that triggers the Customer Data Hub Profile Definition API to pull in which audiences and badges could potentially be assigned to a visitor.

This information is stored within the CMS and continually referenced in the following steps.

1. A script should exist in the CMS that runs the following code to capture the Visitor ID.
2. The script should run on page load and only if the CMS does not already have the Visitor ID.
   

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

   This code pulls the value of the v_id key from the utag_main cookie namespace, also known as  utag.data["cp.utag_main_vi_id"].

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 AudienceStream profile. For example, the TiQ profiles tealium/audiencestream and tealium/tiq may point to the AudienceStream 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 Customer Data Hub Profile Definition API to see the names of which Audiences and Badges are assigned to the specific visitor. This will allow:

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