About Data Layer Enrichment Public API
The Data Layer Enrichment Public API allows you to retrieve a visitor profile for a known visitor ID while that visitor has an active visit. You can combine the Data Layer Enchrichment Public API with the Customer Data Hub Profile Definition API to improve personalization experience on your websites.
How it works
When the Data Layer Enrichment Public API receives a request, the API verifies if there is a whitelisted domain in your Customer Data Hub profile. If a whitelist is available, the Data Layer Enrichment Public API attempts to match the referrer with the whitelisted domains.
The API verification can return the following results depending on the profile:
- No whitelist found
If there is no whitelist available, the Data Layer Enrichment Public API uses the visitor ID in the URL. - Whitelist found, domains match
If the referrer and the whitelisted domains match, the Data Layer Enrichment Public API 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, the Data Layer Enrichment Public API gets the visitor ID from the URL.
The Data Layer Enrichment Public API uses the TAPID cookie when the referrer matches the whitelisted domain, otherwise the API uses the visitor ID from the URL.
Next page personalization
You can combine the Customer Data Hub Profile Definition API and the Data Layer Enrichment Public API to improve personalized experiences for your website visitors. In this example, we want to enable next page personalization on a website that uses a content management system (CMS).
To retrieve the Customer Data Hub profile for a known visitor ID, run an automated script in the CMS at a given interval (for example, once per hour) to trigger the Customer Data Hub Profile Definition API. The API will import the audiences and badges that could potentially be assigned to a visitor. The CMS stores the audience and badge information for use with the Data Layer Enrichment Public API.
This information is stored within the CMS and continually referenced in the following steps:
-
Create a script in the CMS that runs the following code to capture the visitor ID:
document.cookie.match(/v_id:([^$]+)/)[1]
Ensure the script runs on page load and only if the CMS does not already have the visitor ID.
This script imports the value of the v_id
key from the utag_main
cookie namespace, also known as utag.data["cp.utag_main_v_id"]
.
The account and profile imported into the script refer to the AudienceStream account and profile. Many clients have a Tealium iQ Tag Mangement profile that differs from an AudienceStream profile. For example, the Tealium iQ profiles tealium/audiencestream
and tealium/tiq
may point to the AudienceStream profile tealium/main
.
-
Trigger the Data Layer Enrichment Public API.
-
With the response of the Data Layer Enrichment Public API, 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 comparison allows you to implement the following personalization actions:
- 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 Data Layer Enrichment Public API and captures the latest profile for next page personalization.
Retrieving a visitor profile with the Customer Data Hub Profile Definition API
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 using the Customer Data Hub Profile Definition API.
Use the following GET command to retrieve a Customer Data Hub profile definition:
GET http(s)://visitor-service.tealiumiq.com/datacloudprofiledefinitions/{account}/{profile}
Example response
{
"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 Public API honors requests from all domains. If you want to limit these requests from only specific domains, whitelist them in your Customer Data Hub profile. Whitelisting prevents 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, the Data Layer Enrichment Public API will use only 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
is included.
Subdomain examples
http://example.com
https://mobile.example.com/xyz/index.html
http://app.mobile.example.com
Complete the following steps to create a whitelist in your Customer Data Hub profile:
- Navigate to your Customer Data Hub profile.
- From the gear icon in the top right of the screen, select Data Layer Enrichment.
- Enter the comma-separated list of domains you trust. You can add a maximum of 250 domains per profile.
Do Not insert thehttp
orhttps
protocol before the domain. - Click Save.
- Click Save/Publish to save and publish your changes.
TAPID issues and visitor switching
AudienceStream gives the ID in the TAPID
cookie precedence over other IDs to determine the visitor profile to use and provides parameters that control how the endpoint handles ID priority.
For example, if a user logs in and their ID is added to the TAPID
cookie, traffic from all the anonymous users on the device are logged to that user. AudienceStream will continue to log activity to the first user if a second user logs in to that device with an anonymous cookie. For example, if visitors use a shared smart television or a public kiosk, the visitors’ profile data can become contaminated.
This page was last updated: February 8, 2023