Hosted Data Layer API

Hosted Data Layer API

by on ‎08-31-2016 11:32 AM - edited on ‎09-12-2018 07:58 AM by Community Manager (5,758 Views)

The Hosted Data Layer API allows you to upload and access data layer objects or JSON files on the Tealium Multi-CDN. Hosted data layer objects are static JavaScript files that can be fetched by your website to supplement the on-page data layer. JSON files can be used in a variety of applications to transmit data efficiently. Before you begin, it is important to understand the key concepts of the Hosted Data Layer feature.

This article covers the following topics:

Table of Contents Placeholder

Prerequisites

  • 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 API is commonly used in conjunction with the Hosted Data Layer extension.

Naming Guidelines

Before uploading hosted data layer objects, you must know what to name the object and the value of the lookup variable. The name of the hosted data layer object must match the expected value of the lookup variable on the page. The name of the lookup variable becomes the value of the datalayer_id parameter, which is the shared link between the on-page data layer and the data layer object hosted on the CDN.

Hosted JSON files, which are not directly related to the on-page data layer, can have any name that conforms to the URI restrictions below.

Example:

 Description Value
Lookup variable  product_id
Value populated on the page  prod123456
Data layer on page  utag_data.product_id = ["prod123456"];
Hosted data layer object name  prod123456

Object names 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 hosted 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. Save this file with a name following guidelines, for example: prod123456.json.
  3. Make an HTTPS POST request to upload the hosted data layer object to the Tealium CDN.
  4. (Optional)
    Use the following command to preview the uploaded data layer object:
    https://tags.tiqcdn.com/dle/{account}/{profile}/{datalayer_id}.js

    (For JSON files use the .json file extension.)

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

API Rate Limit

While Tealium does not enforce an API rate limit, it is recommended to throttle your own access to this API to under 100 requests/second to maintain a stable integration.

Upload

Use the following POST command to upload a hosted data layer object:

POST /v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer_id}

Use the following POST command to upload a JSON file:

POST /v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer_id}?file-type=json

Curl Request

Use the following cURL command to execute this task:

curl -X POST https://api.tealiumiq.com/v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer id}} \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{ "key1" : "value1", "key2" : "value2" }'

When passing files to the -d parameter using the cURL command, the file name must be prefixed with the @ character.

Example Response

The following example shows a typical response generated from the cURL command. Request rates vary up to a maximum of 100 requests per second, depending on network traffic. It may take up to one (1) hour for changes to be reflected in the CDN.

Status 200 OK

Error Messages

The following table describes potential error messages for this task:

Error Message Description

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 datalayer_id exceeds 250 characters
  • The datalayer_id contains restricted characters
  • There is a typographical error in the account/profile name
  • The request body is empty
  • Bad or invalid JSON
  • JSON data exceeds 1MB
  • The file-type parameter contains a value other than "json" or "javascript".
{
   "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

Use the following PUT command to update a hosted data layer object:

PUT /v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer_id}

Use the following PUT command to update a JSON file:

PUT /v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer_id}?file-type=json

Curl Request

Use the following cURL command to execute this task:

curl -X PUT https://api.tealiumiq.com/v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer id} \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{ "key1" : "value1", "key2" : "value2" }

Example Response

The following example shows a typical response generated from the cURL command:

Status 200 OK

It may take up to one (1) hour for changes to be reflected in the CDN.

Error Messages

The following table describes potential error messages for this task:

Error Message Description
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 datalayer_id exceeds 250 characters
  • The datalayer_id contains restricted characters
  • There is a typographical error in the account/profile name
  • The request body is empty
  • Bad or invalid JSON
  • JSON data exceeds 1MB
  • The file-type parameter contains a value other than "json" or "javascript"
{
   "returnCode" : 1400,
   "message" : "Invalid request submission. Please check supplied parameters or request body."
}

Delete

Use the following command to delete a hosted data layer object:

DELETE /v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer_id}

Use the following command to delete a JSON file:

DELETE /v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer_id}?file-type=json

Curl Request

Use the following cURL command to execute this task:

curl -X DELETE https://api.tealiumiq.com/v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer id} \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json'

Example Response

The following example shows a typical response generated from the cURL command. Request rates vary up to a maximum of 100 requests per second, depending on network traffic. It may take up to one (1) hour for changes to be reflected in the CDN.

Status 200 OK

Error Messages

The following table describes potential error messages for this task:

Error Message Description

400 Bad request

This error occurs when one of the following is true:

  • The combination of account, profile, and datalayer_id exceeds 250 characters
  • The datalayer_id contains restricted characters
  • There is a typographical error in the account/profile name
  • The file-type parameter contains a value other than "json" or "javascript"
{
   "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 File Info

Once a file has been uploaded, you can retrieve meta data about the file using this GET method. A 200 response with a return object validates that your file was uploaded successfully.

If you receive a 404 response for a file, especially after several attempts, use the failed-uploads call to look for the file in the returned list. A failed upload indicates a possible issue in the file transfer process, so you should attempt the upload again.

Use the following GET command retrieve the file info of a hosted data layer object:

GET /v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer_id}

Use the following GET command retrieve the info of a JSON file:

GET /v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer_id}?file-type=json

Curl Request

Use the following cURL command to execute this task:

curl -X GET https://api.tealiumiq.com/v2/dle/accounts/{account}/profiles/{profile}/datalayers/{datalayer id} \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json'

Example Response

The following example shows a typical response generated from the cURL command:

{
  "file": "dle/tealium/main/datalayer1.js",
  "lastModified": "2017-04-07T02:41:24+0000",
  "size": 70
}

Error Messages

The following table describes potential error messages for this task:

Error Message Description

404 Not Found

This error occurs when the supplied datalayer_id does not exist.

{
  "returnCode" : 1404,
  "message" : "Could not locate data layer identified by {datalayer_id}"
}

400 Bad request

This error occurs when one of the following is true:

  • The combination of account, profile, and datalayer_id exceeds 250 characters
  • The datalayer_id contains restricted characters
  • There is a typographical error in the account/profile name
  • The file-type parameter contains a value other than "json" or "javascript"
{
   "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

Use one of the following commands to return a list of up to 1,000 hosted data layer objects and JSON files. If a continuation token is received in the response, the continuation token query parameter can be used for lists greater than 1,000.

GET /v2/dle/accounts/{account}/profiles/{profile}/datalayers

Curl Request 

Use one of the following cURL commands to execute this task:

Curl Request (No Continuation Token)

curl -X GET 'https://api.tealiumiq.com/v2/dle/accounts/{account}/profiles/{profile}/datalayers' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json'

Curl Request (With Continuation Token)

curl -X GET 'https://api.tealiumiq.com/v2/dle/accounts/{account}/profiles/{profile}/datalayers?continuationToken={continuation_token}' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json'

Example Response

The following examples show typical responses generated from the cURL command:

Example Response  (No Continuation Token)

{
  "isTruncated": false,
  "fileStatuses": [
    {
      "file": "dle/tealium/main/datalayer1.js",
      "lastModified": "2017-04-07T02:41:24+0000",
      "size": 70
    },
    {
      "file": "dle/tealium/main/datalayer2.js",
      "lastModified": "2017-04-06T23:37:17+0000",
      "size": 69
    },
    {
      "file": "dle/tealium/main/datalayer3.json",
      "lastModified": "2017-04-07T02:40:30+0000",
      "size": 86
    },
    ...
  ]
}

Example Response  (With Continuation Token)

{
 "isTruncated": true,
 "continuationToken":"1bQZQPYomjLBOQxhZhMazJVoPcrW9iEtOcPhcRQVlMZWx9IssfpisOKt0Kb85bVlRDbkR7NR%2BZd3eUgB0vnx5eomAoz5KX0K2qgcNMOwiJXdbN5CtD4A%2B%2FLK%2B%2Fj0AJ1eYXEu2l%2F9Z%2FGk%3D", 
 "fileStatuses": [
   {
     "file": "dle/tealium/main/datalayer1.js",
     "lastModified": "2017-04-07T02:41:24+0000",
     "size": 70
   },
   {
     "file": "dle/tealium/main/datalayer2.js",
     "lastModified": "2017-04-06T23:37:17+0000",
     "size": 69
   },
   {
     "file": "dle/tealium/main/datalayer3.json",
     "lastModified": "2017-04-07T02:40:30+0000",
     "size": 86
   },
   ...
 ]
}

Error Messages

The following table describes potential error messages for this task:

Error Message Description

400 Bad request

This error occurs due to a typographical error in the account/profile name.

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

401 Unauthorized

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

Failed Uploads

Use the following command to query for failed uploads. The results returned will contain a maximum of 5,000 records and are not paginated. A failed upload indicates a possible issue in the file transfer process, so you should attempt the upload again.

Results can be filtered using the following date range parameters:

  • start-date : (optional) only failed uploads with a date equal to or later than this value will be returned.
  • end-date : (optional) only failed uploads with a date equal to or earlier than this value will be returned.

Expected format:  YYYY-MM-DDTHH:MM:SSTZ
Example: "2017-03-31T13:45:33-0700"

GET /v2/dle/accounts/{account}/profiles/{profile}/failed-uploads?start-date={start_date}&end-date={end_date}

Curl Request

Use the following cURL command to execute this task:

curl -X GET 'https://api.tealiumiq.com/v2/dle/accounts/{account}/profiles/{profile}/failed-uploads?start-date={YYYY-MM-DDThh:mm:ssZ}&end-date={YYYY-MM-DDThh:mm:ssZ}' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/json'

Example Response

The following example shows a typical response generated from the cURL command:

Status 200 OK 
{
  "account": "your_account",
  "profile": "main",
  "count": 2,
  "failedUploads": [
    {
      "file": "/dle/your_account/main/forremoval2.js",
      "date": "2017-05-20T17:22:00+0000"
    },
    {
      "file": "/dle/your_account/main/forremoval.js",
      "date": "2017-05-20T17:22:00+0000"
    }
  ]
}

Error Messages

The following table describes potential error messages for this task:

Error Message Description

400 Bad request

This error occurs when one of the following is 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"
}