Skip to main content

Capturing Custom Data (pdata) for Client-Side Tags Implemented Via ATS

Abstract

When implementing the Enhanced Client-Side Tag (eCST) via the ATS for Web integration, 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.

When implementing the Enhanced Client-Side Tag (eCST) via the ATS for Web integration, 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.

Note

When implementing the Enhanced Client-Side Tag (eCST) via the standard methods, you can also capture custom data, but the process is different. For more information, see “Capturing Custom Data (pdata) for Client-Side Tags (Standard Implementation)”.

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 in this article.

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 JavaScript function for pdata).

Implementing the Tag to Capture Custom Data (pdata)

To send custom data (pdata), add the following JavaScript function to the JavaScript present on the page, replacing the key-value pairs shown below with custom data you want to send:

__launchpad('ecst', {key1: 'value1', key2: 'value2'})

When constructing the string, use these parameters:

  • "<key1>" is the value for key 1 (the key of the first key-value pair of custom data)

  • "<value1>" is the value for value 1 (the value of the first key-value pair of custom data)

  • "<key2>" is the value for key 2 (the key of the second key-value pair of custom data)

  • "<value2>" 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:

  • Do not include commas (",") or equals signs ("=") in keys or values, as this results in incorrect parsing of the data. See "Replacing Commas and Equal Signs in pdata Keys and Values” section below for more information.

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

  • 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" 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

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.