Tealium Learning Center

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. In this article: 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. GET a Visitor Profile Use the following GET command to retrieve a visitor profile: GET http(s)://visitor-service.tealiumiq.com/{account}/{profile}/{visitor_id} Example response { "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 returns 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 Tealium AudienceStream CDP has not finished processing the AudienceStream request, meaning the visitor profile is not yet available at the time of the Data Layer Enrichment request, 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. Use Case – 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_vi_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 the http / https 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. For more information and a demonstration of how to use visitor switching, see Visitor Switching. ... View more