Hosted Data Layer API

Hosted Data Layer API

by on ‎08-31-2016 11:32 AM - edited Tuesday by (2,567 Views)

The Hosted Data Layer API is a component of the Hosted Data Layer feature. This component allows you to upload and access data layer objects on the CDN. The data layer objects are static JSON objects that can be fetched by your website to supplement the on-page data layer.

Before You Begin

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

Prerequisites

The following items are required to implement this feature:

  • Hosted Data Layer Extension
    This is the first component of the Hosted Data Layer feature. The purpose of this component is to enrich the Hosted Data Layer objects into the target data layers. You must add and configure the Hosted Data Layer extension before uploading the data layer objects to the CDN.
  • Save or Save-As Permissions
    If you do not currently have Save or Save-As permissions, contact your account administrator to grant either permission.

This article covers the following topics:

Table of Contents Placeholder

Naming Guidelines

Before uploading a data layer object, you must know what to name the object. The name of the data object uploaded must match the value of the lookup variable (data layer) on the page. Use the Hosted Data Layer API to upload static information about these products. 

You must know the value of the lookup variable first and then name the hosted data layer objects to match the expected values. The name of the lookup variable becomes the shared link between the on-page data layer and the data layer object hosted on the CDN.

Example:

For example, the name of a data layer object for the lookup variable product_id must match the value populated on the page, e.g. "prod123456". If the variable on the page is product_id, the value will be the ID of the product being viewed, such as "prod123456".

  • Data Layer on page: utag_data.product_id = ["prod123456"];
  • Hosted Data Layer Object name: "prod123456"
  • The name of your data layer object becomes the value of the dl_id parameter.

The name must not contain whitespace or the following Uniform Resource Identifier (URI) reserved characters:  / : ? # [ ] @ ! $ & ' ( ) * + , ; = % . " 

Creating a Hosted Data Layer Object

Use the following steps to create a data layer object:

  1. Define the new variables in a flat JSON file, as shown in the following example:
    {
        "product_category"           : ["Accessories"],
        "product_brand"              : ["Acme"],
        "product_sku"                : ["GEN-PRD-BLU"],
        "product_has_free_shipping"  : ["0"],
        "product_has_instore_pickup" : ["1"]
    }

    The JSON payload should not exceed 1 MB.

  2. Set the file name according to the naming guidelines, e.g. "prod123456.json".

  3. Make an HTTPS POST request to upload the object on the Tealium CDN.

  4. (Optional) Preview the uploaded JSON URL of the following format:
    https://tags.tiqcdn.com/dle/{account}/{profile}/{dl_id}.js

    The account name, profile name, and dl_id names combined should not exceed 250 characters.


Upload

Upload a Hosted Data Layer object.

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

Using PUT instead of POST will result in a 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"

When passing files to the -d parameter in curl, the file name must be prefixed with the "@" character.

Example Response

Status 201 OK

{ 
   "status": "pending" 
}

It may take five (5) to ten (10) minutes for changes to be reflected in the CDN. Wait for the status to display 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:

  • The JSON key contains a period
  • The combination of account, profile, and dl_id exceeds 250 characters
  • The dl_id contains restricted characters
  • The user does not have the appropriate permissions
  • There is a typographical error in the account/profile name
  • The request body is empty
  • Bad or invalid JSON
  • JSON data exceeds one (1) mebibyte (MiB)
{
   "returnCode" : 1400,
   "message" : "Invalid request submission. Please check supplied parameters or request body."
}

401 Unauthorized

This error occurs when the user lacks the appropriate permissions or there is a typographical error 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}

Using PUT instead of POST will result in a 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 one (1) hour for changes to be reflected in the CDN.Wait for the status to display 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:

  • The JSON key contains a period
  • The combination of account, profile, and dl_id exceeds 250 characters
  • The dl_id contains restricted characters
  • The user does not have the appropriate permissions
  • There is a typographical error in the account/profile name
  • The request body is empty
  • Bad or invalid JSON
  • JSON data exceeds one (1) mebibyte (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 one (1) hour for changes to be reflected in the CDN.Wait for the status to display 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
  • The dl_id contains restricted characters
  • The user does not have the appropriate permissions
  • There is a typographical error 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 a lack of appropriate permissions or a typographical error 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. Statuses are only retained for 30 days.

Expected status values are:

  • 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 the supplied dl_id does not exist or the status for the supplied dl_id has expired because it extends beyond the 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
  • The dl_id contains restricted characters
  • The user does not have the appropriate permissions
  • There is a typographical error 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 a lack of appropriate permissions or a typographical error 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 1,000 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

This error occurs due to a lack of appropriate permissions or a typographical error in the account/profile name.

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

400 Bad Request

More than 1,000 hosted data layers were found for the account/profile.

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

401 Unauthorized

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