About Data Layer Enrichment Public API

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:

1. 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.

1. Trigger the Data Layer Enrichment Public API.

2. 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:

1. Navigate to your Customer Data Hub profile.
2. From the gear icon in the top right of the screen, select Data Layer Enrichment.
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 or https protocol before the domain.
4. Click Save.
5. 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.