- TLC Home Home
- Discussions & Ideas Discussions & Ideas
- Product Guides Product Guides
- Knowledge Base Knowledge Base
- Developer Docs Developer Docs
- Education Education
- Blog TLC Blog
- Support Desk Support Desk
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:
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:
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.
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.
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:
http
/ https
protocol before the domain.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:
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.
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.
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"]
.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
.
You can now trigger the Visitor Profile API.
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:
Copyright All Rights Reserved © 2008-2021