Data Layer Enrichment

Data Layer Enrichment

by Community Manager ‎08-31-2016 11:32 AM - edited ‎05-11-2017 09:58 PM (1,718 Views)

The Data Layer Enrichment (DLE) API is a component of the Data Layer Enrichment feature. It allows you to host Data Layer objects on Tealium's CDN. The objects are static JSON objects that can be fetched by your website to supplement the on-page data layer.

Before You Begin

Read the Data Layer Enrichment - Tealium iQ overview to understand the key concepts of this feature. 

Prerequisites

  • Data Layer Enrichment Extension: This is the first component of the DLE feature. It's purpose is to enrich the hosted Data Layer Objects into the target Data Layers. It's imperative to add and configure it before uploading the Data Layer Objects to the CDN.
  • Save or Save-As permissions: Please contact your account administrator to grant you either permission, if you don't already have it.

In this article:

Table of Contents Placeholder

Data Layer Object Naming Guidelines

Before uploading a Data Layer Object, you must know what name to give it. The name of the uploaded data object will match the value of the lookup variable (data layer) on the page. For example, a variable on the page might be product_id and the value will be the ID of the product being viewed eg. "prod123456". You want to use the DLE API to upload static information about these products. The name of a data layer object for this lookup variable (product_id) must match the value populated on the page, for example "prod123456".

The lookup variable becomes the common thread between the Data Layer being enriched on the page and the Data Layer Object hosted on the CDN. For this reason, you must know the lookup variable first, then name the hosted Data Layer Objects to match the expected values. 

Example

  • Data Layer on page: utag_data.product_id = ["prod123456"];
  • Hosted Data Layer Name: "prod123456"

The name of your Data Layer Object becomes the value of the dl_id parameter.

Make sure the name does not contain whitespace and URI reserved chars / : ? # [ ] @ ! $ & ' ( ) * + , ; = % . " 

Creating a Data Layer Object

  1. Define the new Variables in a flat JSON file. Here's an example: 
    {
        "product_category"           : ["Accessories"],
        "product_brand"              : ["Acme"],
        "product_sku"                : ["GEN-PRD-BLU"],
        "product_has_free_shipping"  : ["0"],
        "product_has_instore_pickup" : ["1"]
    }
    

    JSON payload should not exceed 1 MB.

  2. Set the file name according to the naming guidelines eg. "prod123456.json"
  3. Make an HTTPS POST request to upload the object on Tealium's CDN.
  4. (Optional) Preview the uploaded JSON URL of this format: https://tags.tiqcdn.com/dle/{account}/{profile}/{dl_id}.js 

Account name, profile name, and dl_id together should not exceed 250 chars. 

Upload

Upload a Data Layer Enrichment object.

POST /v1/dle/accounts/{account}/profiles/{profile}/datalayers/{dl_id}?utk={token}

CAUTION: Using PUT instead of POST will result in 405 Method Not Allowed error.

Curl Request

curl  -i -b JSESSIONID={session_id} \ 
  https://api.tealiumiq.com/v1/dle/accounts/{account}/profiles/{profile}/datalayers/{dl_id}?utk={token} \ 
  -d {dl_id}.json -X POST -H "Content-Type: application/json"

Example Response

Status 201 OK

{ 
   "status": "pending" 
}

It may take around 5 to 10 mins for changes to be reflected in the CDN. Wait for the status to come back as completed before attempting to make another call on the same dl_id

Error Messages

405 Method not allowed: This error occurs when you use PUT instead of POST to perform the upload.

{
   "returnCode" : 1464,
   "message" : "Resource already exists. Updates are not permitted via this type of request."
}

 

400 Bad request: This error occurs when one of the following is true:

  • JSON key contains a period
  • The combination of account, profile, and dl_id exceeds 250 characters
  •  dl_id contains restricted characters
  • User lacks proper permissions or there's a typo in the account/profile name
  • Request body is empty
  • Bad or invalid JSON
  • JSON data exceeds 1 MiB
{
   "returnCode" : 1400,
   "message" : "Invalid request submission. Please check supplied parameters or request body."
}

401 Unauthorized: Lack of proper permissions or possibly a typo in the account/profile name

{
   "returnCode" : 1469,
   "message" : "although the user is authenticated, the request is denied because of a lack of proper permissions"
} 

Update

PUT /v1/dle/accounts/{account}/profiles/{profile}/datalayers/{dl_id}?utk={token}

CAUTION: Using POST instead of PUT will result in 405 Method Not Allowed error.

Curl Request

curl -i -b JSESSIONID={session_id} \ 
  https://api.tealiumiq.com/v1/dle/accounts/{account}/profiles/{profile}/datalayers/{dl_id}?utk={token} \ 
  -d {dl_id}.json -X PUT -H "Content-Type: application/json"

Example Response

Status 200 OK

{ 
   "status": "pending" 
}

It may take up to 1 hour for changes to be reflected in the CDN. Wait for the status to come back as "completed" before attempting to make another call on the same dl_id.

Error Messages

400 Bad request: This error occurs when one of the following is true:

  • JSON key contains a period
  • The combination of account, profile, and dl_id exceeds 250 characters
  •  dl_id contains restricted characters
  • User lacks proper permissions or there's a typo in the account/profile name
  • Request body is empty
  • Bad or invalid JSON
  • JSON data exceeds 1 MiB
{
   "returnCode" : 1400,
   "message" : "Invalid request submission. Please check supplied parameters or request body."
}

404 Not Found: This error occurs if the supplied dl_id does not exist.

{
   "returnCode" : 1404,
   "message" : "Could not locate data layer for supplied params ([account]/[profile]/[dl_id])."
} 

Delete

DELETE /v1/dle/accounts/{account}/profiles/{profile}/datalayers/{dl_id}?utk={token}

Curl Request

curl -i -b JSESSIONID={session_id} \ 
  https://api.tealiumiq.com/v1/dle/accounts/{account}/profiles/{profile}/datalayers/{dl_id}?utk={token} \ 
  -X DELETE -H "Content-Type: application/json"

Example Response

Status 200 OK

{ 
   "status": "pending" 
}

It may take up to 1 hour for changes to be reflected in the CDN. Wait for the status to come back as "completed" before attempting to make another call on the same dl_id.

Error Messages

404 Not Found: This error occurs if the supplied dl_id does not exist.

{
   "returnCode" : 1404,
   "message" : "Could not locate data layer for supplied params ([account]/[profile]/[dl_id])."
}

400 Bad request: This error occurs when one of the following is true:

  • The combination of account, profile, and dl_id exceeds 250 characters
  •  dl_id contains restricted characters
  • User lacks proper permissions or there's a typo in the account/profile name
{
   "returnCode" : 1400,
   "message" : "Invalid request submission. Please check supplied parameters or request body."
}

401 Unauthorized: This occurs due to lack of proper permissions or possibly a typo in the account/profile name.

{
   "returnCode" : 1469,
   "message" : "although the user is authenticated, the request is denied because of a lack of proper permissions"
}

 

Get Status

Get the status of upload, update, and delete actions. All statuses are retained for 30 days only. Expected status values: pending, completed, failed.

GET /v1/dle/accounts/{account}/profiles/{profile}/datalayers/{dl_id}?utk={token}

Curl Request

curl -i -b JSESSIONID={session_id} \
    https://api.tealiumiq.com/v1/dle/accounts/{account}/profiles/{profile}/datalayers/{dl_id}?utk={token}

 Example Response

{ 
   "status": "completed" 
}

Error Messages

404 Not Found: This error occurs when:

  • Supplied dl_id does not exist
  • Or the status for the supplied dl_id has expired (> 30-day retention period)
{
   "returnCode" : 1404,
   "message" : "Status unavailable. Please refer to documentation for request status retention period."
} 

400 Bad request: This error occurs when one of the following is true:

  • The combination of account, profile, and dl_id exceeds 250 characters
  •  contains restricted characters
  • Lack of proper permissions or possibly a typo in the account/profile name
{
   "returnCode" : 1400,
   "message" : "Invalid request submission. Please check supplied parameters or request body."
}

401 Unauthorized: This error occurs due to lack of proper permissions or possibly a typo in the account/profile name

{
   "returnCode" : 1469,
   "message" : "although the user is authenticated, the request is denied because of a lack of proper permissions"
}

List

Returns a list of up to 1000 hosted Data Layer names.

GET /v1/dle/accounts/{account}/profiles/{profile}/datalayers?utk={token}

Curl Request

curl -i -b JSESSIONID={session_id} \ 
  https://api.tealiumiq.com/v1/dle/accounts/{account}/profiles/{profile}/datalayers?utk={token}

Example Response

Status 200 OK.

{ 
   ["demo_1","demo_2","demo_3"]
} 

Error Messages

400 Bad request: Lack of proper permissions or possibly a typo in the account/profile name.

{
   "returnCode" : 1400,
   "message" : "Invalid request submission. Please check supplied parameters or request body."
}

400 Bad Request: More than 1000 hosted Data layers were found for the account/profile.

{
   "returnCode" : 1400,
   "message" : "Invalid request submission. Data layer list size exceeds maximum permissible (1000)."
}

The complete list of hosted Data Layers is made available through an S3 bucket assigned to your account/profile. To get the access credentials for the bucket, please submit a request through our Support Desk Portal.

 

401 Unauthorized

{
   "returnCode" : 1469,
   "message" : "although the user is authenticated, the request is denied because of a lack of proper permissions"
}