Capturing Custom Data (pdata) for Client-Side Tags

Abstract

You can capture custom data, in addition to the data that is captured automatically, by using "pdata" in your tag. Pdata are optional, key-value segment data that are included in your tag and sent to LiveRamp with the impression.

You can configure any desired information that is within our privacy guidelines to be passed as pdata. Make sure to also follow our requirements for custom data listed below.

If a tag contains pdata, the values captured on each impression will be returned in the log files (for measurement use cases in our File-Based Recognition workflow) or placed into key-value segments associated with that pdata in Connect (for activation use cases).

Caution

Do not capture URL strings as values in pdata. URLs are captured in a privacy-safe manner as part of the data automatically captured. Passing URL strings as values in pdata poses a privacy risk where in the worst-case scenario, personally identifiable information (PII) is included in the string.

Use of pdata is optional. If you do not have custom segment data you wish to include with the impressions, do not include the parameter at all (i.e., do not include the "&pdata=<PDATA>" string shown in the GET formatting examples or the JSON object shown in the POST examples).

Implementing the Tag to Capture Custom Data (pdata)

To implement the tag to capture custom data, follow the appropriate example for your implementation method:

If you implement the tag via GET, the pdata is included as a string in the URL after the "<TAG ID>" parameter in this format:
&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>

If you implement the tag via POST, the pdata are included in a JSON object after the URL:

-H 'Content-Type: application/json' \

-d '{

"segments": {

"<k1>": "<v1>",

"<k2>": "<v2>"

}

}'

For either request method, use these parameters:

"<k1>" is the value for key 1 (the key of the first key-value pair of custom data)
"<v1>" is the value for value 1 (the value of the first key-value pair of custom data)
"<k2>" is the value for key 2 (the key of the second key-value pair of custom data)
"<v2>" is the value for value 2 (the value of the second key-value pair of custom data)

Note

Include only as many key-value pairs as is appropriate for your implementation.

Requirements for Custom Data

When using pdata to capture custom data, follow the requirements listed below:

If you implement the tag using GET request methods, do not include commas (",") or equals signs ("=") in keys or values, as this results in incorrect parsing of the data. See “Replacing Commas and Equals Signs in pdata Keys and Values” below for more information.
If you implement the tag using GET request methods, make sure that the entire string after "pdata=" is URL-encoded so that non-alphanumeric characters such as "/" can be properly parsed. This includes both the equals sign ("=") separating the keys and values and the commas (",") separating the key-value pairs, as well as any non-alphanumeric characters in the keys and values themselves. For example, something like "pdata=visitor=new" will not work because it is not URL encoded.
Do not pass URL strings as values in pdata. This can be a privacy risk where, in the worst-case scenario, PII (personally identifiable information) is included in the string. LiveRamp provides a privacy-safe URL value for the page on which the pixel was fired, described in the “Data Automatically Captured” section of this document.
For online Onboarding use cases, a minimum of 25 devices must populate each segment (for example, if "Gender=Male" is the segment being populated, it must have at least 25 devices). This is a privacy guidelines. This does not apply to data collected for use cases (such as some measurement use cases) that use our File-Based Recognition workflow.
When using ad server macros to populate pdata "values", connect with your ad server partner to understand what values (if any) will be passed when a macro cannot access the data element associated with the macro. This is important, because if the macro leaves the "value" blank, then the Enhanced Client-Side Tag (eCST) will fail to fire properly and will error (status code: 400). An easy trick to circumnavigate this issue with ad servers is to place an underscore after the macro so that there will always be a value (_) for pdata key/value pairs, even in the event that the macro doesn't populate with the intended value.
Make sure that the pdata contains at least one key/value pair. That is, "https://di.rlcdn.com/api/segment?pid=1234&pdata=" in a GET implementation is not allowed.
Make sure that all keys have values. That is, something like "&pdata=<k1>%3D" in a GET implementation is not allowed because key 1 does not have a value.
Make sure that all values have keys. That is, something like "=value1" in a GET implementation is not allowed.
Do not include more than 400 unique keys per tag ID. Not every call must contain the same keys, but across all calls on a particular tag ID, the sum of unique keys should not exceed 400.
Do not include the same key multiple times within the pdata passed in a given call. That is, something like "key1=value1,key1=value2" in a GET implementation is not allowed.
For a given key to support enumerated fields (both within Connect or in LiveRamp's systems in general), do not pass more than 250 distinct values per key for Onboarding workflows.

Warning

Requirements must be followed: Any calls made to LiveRamp that do not meet the above requirements will be rejected with a 4xx error, the impression will not be logged, and the impression data not included in the subsequent data ingestion job.

Replacing Commas and Equals Signs in pdata Keys and Values

When implementing via GET, make sure not to include commas (",") or equals signs ("=") within keys or values, as an equal sign will be interpreted as the end of the key, and a comma will be interpreted as the end of a value. This results in incorrect parsing of the key or value.

Replace any equal signs or commas within keys or values with a different character, such as an underscore ("_") character. For example, say you had either of the following key-value segments: "shirt=red=true" or "shirt,red=true". Since you cannot include "shirt=red" or "shirt,red" as a key in pdata, you might use an underscore instead and include “shirt_red” instead.

Tag Example Using pdata

Here is an example of a tag implemented using the GET request method utilizing pdata to capture the custom data "visitor=yes" and "category=home" after the pdata string has been URL-encoded per the requirements:

https://di.rlcdn.com/api/segment?pid=1234&pdata=visitor%3Dyes%2Ccategory%3Dhome

Because the pdata has been URL-encoded in accordance with the pdata requirements listed above, the equals signs have been converted to "%3D" and the commas have been converted to "%2C" (for help encoding, we recommend this tool).

The above impression would be placed into the following key-value segments:

visitor = yes
category = home

In this section:

enumerated fieldsdistinct values