Implementing LiveRamp's Client-Side Tag

The LiveRamp Client-Side Tag (CST) is a tag that can be used to log user activities (such as page views, adding items to a cart, or completing a transaction) and group them into segments.

If you're using the tag for measurement (our File-Based Recognition workflow), these segments can be delivered back to you or your measurement partner in batch files that include the corresponding RampID(s) for the online identifier captured. You can choose to receive one RampID for each identifier or to receive multiple RampIDs for each identifier (if there are more than one).

If you're using the tag for activation, the segments can be automatically imported into LiveRamp Connect, where you can distribute them to your desired destinations.

LiveRamp has two Client-Side Tag versions:

  • The standard Client-Side Tag (CST), which captures LiveRamp cookies.

  • The enhanced Client-Side Tag (eCST), which can capture LiveRamp cookies and additional identifiers, such as mobile device IDs, OTT and CTV IDs, and Identity Envelopes (containing RampIDs).

Note

The eCST is currently in open beta for measurement use cases (our File-Based Recognition workflow, where log files are delivered back to you and/or a partner) and the use of the eCST requires an update to your contract. In the future, the eCST will also be available for activation use cases (where segments are created in your Connect account). Contact your LiveRamp representative for more information.

Standard Client-Side Tag Capabilities

The standard Client-Side Tag (CST) tracks cookies, and can be placed in any cookieable environment, such as your website, marketing emails, or in online advertisements. You set the tag to fire on the desired user activity.

The CST automatically captures basic URL and log data by default, but additional custom data (“pdata”) can also be captured, depending on your needs. See “Data Automatically Captured” and “Capturing Custom Data (pdata)” below for more information.

Once a day (at 0:00 UTC time), LiveRamp generates log files containing all data logged from the tag in the previous day and then ingests that data. The data is then either delivered to you and/or your partner in batch files or used to create or update segments in your Connect account.

Enhanced Client-Side Tag Capabilities

In addition to the capabilities of the standard CST, the Enhanced Client-Side Tag (eCST) can also be placed in mobile web applications, in-app mobile, or CTV environments.

In addition to the cookies that are captured automatically, the eCST can also collect the following identifier types (depending on the environment the tag is placed in):

  • Mobile device IDs (IDFAs and AAIDs)

  • Over The Top (OTT) and Connected TV (CTV) IDs

  • Identity Envelopes (that contain RampIDs)

The eCST can also track authentications on websites or mobile web apps by capturing Identity Envelopes generated using LiveRamp's Authenticated Traffic Solution (ATS).

For tag examples for different environments, see “Client-Side Tag Usage and Examples for Different Environments” below.

Once you've initiated the process with your LiveRamp representative, implementing the CST or eCST involves the following steps:

  1. You provide your LiveRamp Implementation team with the following information to begin the process of implementing the tag:

    • What user activity you want to track and which environment(s) you plan to track activity in.

    • For placements in web, mobile web, or advertisements, whether you want to capture only cookies (with the standard CST) or whether you want to capture additional identifiers (with the eCST).

      Note

      Only the eCST can be placed in in-app mobile, OTT, or CTV environments.

    • Whether you want to capture additional custom data (“pdata”) beyond the data that tag captures automatically.

    • Whether you plan to implement the tag as an image tag or iframe (see "Implementation Methods" below).

    • Whether you plan to use the POST or GET request method.

      Note

      Generally, most clients use GET request methods, as they are fairly standard for tracking pixels.

    • Whether you want LiveRamp to deliver the data back to you and/or a partner (for measurement, using our File-Based Recognition workflow), or to create segments from the data in Connect (for activation). For measurement, also determine where you want the files to be delivered and whether you want to receive one or multiples per identifier.

      Note

      The eCST is currently in open beta for measurement use cases (where log files are delivered back to you and/or a partner) but is not currently available for activation use cases. In the future, the eCST will also be available for activation use cases

  2. LiveRamp provides you with a tag ID (sometimes referred to as a “placement ID” or “pid”) and creates the necessary additional audiences in your Connect account (for activation use cases).

  3. You work with your technical team or tag manager to structure the tag properly to capture the desired data.

  4. You send an example of your tag to LiveRamp (e.g., “https://di.rlcdn.com/api/segment?pid=<TAG ID>”).

  5. LiveRamp validates that the tag is formatted correctly and working as expected.

  6. You work with your technical team or tag manager to implement the tag so that it fires on the desired user activity.

  7. Once the segments have been ingested, LiveRamp either delivers the data back to you and/or a partner as log files, or creates segments in a new audience in your Connect account.

See the appropriate sections below for more information.

In addition to the web and mobile web environments where the standard CST can be used, the eCST can now also be used in in-app mobile, OTT, and CTV environments.

See the table below for a breakdown of which identifiers can be captured in the different possible environments.

Environment

Cookies

MAIDs (AAIDs/IDFAs)

CTV/OTT IDs

Identity Envelopes

Notes

Web or Mobile Web

Yes

No

No

Yes

  • Capturing Identity Envelopes requires ATS

In-App Mobile

No

Yes

No

Yes

  • Capturing Identity Envelopes requires ATS

CTV or OTT

No

No

Yes

Yes

  • Capturing Identity Envelopes requires ATS

Advertisements

Yes

Yes

Yes

No

  • Only one identifier can be captured per impression

  • RampIDs will be returned in log files

See the information below for examples of how to place the tag for each of these environments.

Web/Mobile Web for Identity Envelopes

https://di.rlcdn.com/api/segment?pid=1234&it=19&iv=<IDENTITY_ENVELOPE>&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>

In-App Mobile for IDFAs (iOS Devices)

https://di.rlcdn.com/api/segment?pid=1234&it=6&iv=<IDFA>&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>

In-App Mobile for AAIDs (Android Devices)

https://di.rlcdn.com/api/segment?pid=1234&it=5&iv=<AAID>&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>

CTV/OTT for CTV IDs (CTV Devices)

https://di.rlcdn.com/api/segment?pid=1234&it=17&iv=<CTV>&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>

Placing Client-Side Tags in Advertisements

Placing Client-Side Tags in advertisements to capture ad impressions can sometimes present additional complications. This generally comes up when the owner of the ad (using the Client-Side Tag) references data on the web page for pdata; it's possible that the Client-Side Tag will fire before the appropriate data for the pdata variable has loaded, leading to a “nil” value for that field.

Note

LiveRamp's clients do successfully leverage Client-Side Tags in advertisements, but it is important to understand that, depending on when the web page loads, when the ad loads, and when the pixel fires, there is a chance the appropriate data will not yet be available for some number of tag fires. LiveRamp recommends obtaining exposure data directly from the DSP or SSP instead, as this data will be more-reliably collected and available.

Note

Check with your ad server partner to ensure they have valid device identifier macros to populate the device type (the "it" parameter for the eCST) and your preferred custom data (pdata) points.

A common request is to capture ad server macros in the identifier value fields and in pdata. See below for some examples.

Generic example to capture cookies, AAIDs, IDFAs, and CTV IDs::

https://di.rlcdn.com/api/segment?pid=1234&it=5&iv=<AAID_Macro>&it=6&iv=<IDFA_Macro>&it=17&iv=<CTV_Macro>&pdata=AdvertiserID%3D%<AdvertiserID_Macro>%2CCampaignID%3D%<CampaignID_Macro>%2CSiteID%3D%<SiteID_Macro>%2CPlacementID%3D%<PlacementID_Macro>%2CAdID%3D%<AdID_Macro>%2CCreativeID%3D%<CreativeID_Macro>

Note

There is no LiveRamp cookie macro because the eCST will automatically collect a LiveRamp cookie.

Note

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

Click here for a list of common macros across various platforms.

Here is an example with Google Campaign Manager macros captured in pdata:

https://di.rlcdn.com/api/segment?pid=1234&pdata=AdvertiserID%3D%eadv!%2CCampaignID%3D%ebuy!%2CCreativeID%3D%ecid!%2CPlacementID%3D%epid!%2CSiteDCM%3D%s%2CSiteIDDCM%3D%esid!

LiveRamp has found that "%i" (impression macro) does not work, and will throw issues when included in our tag. Other macros should work fine.

Both the CST and eCST can be implemented using the following methods:

  • Via an image tag (recommended). An example of an image tag is “<img style="display: none;" src="https://di.rlcdn.com/api/segment?pid=<TAG ID>&pdata=<PDATA>"/>”. See this link for more information on image tags.

  • Via an iframe (non-standard). An example of an iframe is “<iframe name="_rlcdn" width=0 height=0 frameborder=0 src="https://di.rlcdn.com/api/segment?pid=<TAG ID>&pdata=<PDATA>"</iframe>”. See this link for more information on iframes.

Either of these implementation methods may use either GET or POST request methods to communicate pixel requests with LiveRamp.

Typically, clients implement image tags and utilize GET requests when using the CST or eCST, as that is standard protocol for most tracking pixels used around the web. Technical teams implementing the CST or eCST will be most comfortable using that combination. When in doubt, default to image tags and GET request methods.

Regardless of the pixel type and request method, you will use a similar URL string, which is structured differently depending on the following criteria:

  • If you want to capture additional identifiers beyond cookies, the identifiers you want the tag to capture (the specific identifiers that can be captured are based on the environment you're placing the tag in and these identifier types will need to be specified in your request URL)

  • Whether you're going to use the tag to capture custom data (in addition to the data automatically captured)

See the sections below for specific formatting instructions depending on your implementation method.

By default, the data listed below is automatically captured and stored as segments (with the field names listed below) in LiveRamp for both the CST and the eCST:

  • Tag-ID: The tag ID (pid) that this exposure came from.

  • Ref-URL: The URL of the page where the tag was placed.

  • Impression-Key: A unique identifier for this impression that can be used across audience delivery files (for measurement use cases in our File-Based Recognition workflow). Example: When capturing cookies and Identity Envelopes, one impression may capture both a cookie and an envelope. There will be two files delivered: A cookie file with s and an envelope file with RampIDs. The Impression Key will allow clients to choose the RampIDs they wish to use for impressions when more than one is returned.

  • Log-Date: The date of the exposure in YYYY-MM-DD format (PST).

  • Log-Time: The date and time of the exposure in YYYY-MM-DD-HH:MM:SS format (PST).

  • Log-Time-UTC-Sec: The time of the exposure in Unix time.

Keep the following in mind:

  • For privacy reasons, the URL will be truncated before the first “?” or “=” character in the string.

  • Some reference URLs captured might be missing or confusing - see the FAQs below for more information on how this might happen.

  • If you want to capture additional data beyond what is automatically captured, you can configure the tag to capture custom data (“pdata). See “Capturing Custom Data (pdata)” below for more information.

  • This data is always included: If you choose not to capture any custom segment data through the use of pdata, the above segments will still be included.

  • Don't include the data types listed above in custom data (pdata): Since this data is captured by default, there is no need to add this type of information as custom data (pdata) in your tag. This includes domain information (URLs).

You can capture custom data, in addition to the data that is captured automatically, by utilizing “pdata” in your tag. Pdata is optional, key-value segment data that is 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 pdata listed below.LiveRamp Data Restrictions

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, PII (personally identifiable information) 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 is included as a JSON object after the URL:

    -H 'Content-Type: application/json' \
    
    -d '{
    
    "segments": {
    
    "<k1>": "<v1>",
    
    "<k2>": "<v2>"
    
    }
    
    }'

For either request method, utilize 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 pdata

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 guideline. This does not apply to data collected for use cases (such as some measurement use cases) that utilize our File-Based Recognition workflow.LiveRamp Data Restrictions

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

Use the format shown below when implementing the eCST tag via GET (formatting for the CST is similar).

https://di.rlcdn.com/api/segment?pid=<TAG ID>&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>

To test your tag from Terminal, you can use the following prompt:

curl -X GET https://di.rlcdn.com/api/segment?pid=<TAG ID>&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>

The following parameters are included in the tag example:

  • "<TAG ID>” is the tag ID ("pid") provided to you by LiveRamp

  • "<IDENTIFIER TYPE NUMBER>" is the number for the identifier type you want to capture, when capturing identifiers other than cookies (refer to the section on capturing additional identifiers below for the number to use)

  • "<IDENTIFIER VALUE>" is a valid value for the identifier specified in the "<IDENTIFIER TYPE NUMBER>" parameter

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

The example format shows a tag that has been configured to capture additional identifiers beyond cookies and to capture two key-value pairs of custom data. Modify the format to suit your use case:

  • To use the standard CST (when you only want to capture cookies), leave out the "&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>" string after the "<TAG ID>" parameter.

  • If you do not want to capture custom data (pdata), leave out the "&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>" string.

See the sections below for additional formatting information.

Capturing Additional Identifiers with the eCST

For each identifier (other than cookies) that you want to capture, include a string in the format "&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>" after the tag ID parameter (“pid=<TAG ID>”). Use the appropriate identifier type number shown in the table below.

Note

The eCST is currently in open beta for measurement use cases (our File-Based Recognition workflow, where log files are delivered back to you and/or a partner) and the use of the eCST requires an update to your contract. In the future, the eCST will also be available for activation use cases (where segments are created in your Connect account). Contact your LiveRamp representative for more information.

Identifier Type

Identifier Type Number

Applicable Environment(s)

AAID

5

  • In-app mobile

  • Advertisements

IDFA

6

  • In-app mobile

  • Advertisements

CONNECTED_TV_ID or

OTT_ID

17

  • OTT

  • CTV

IDENTITY_ENVELOPE

19

  • Web

  • Mobile web

  • In-app mobile

  • OTT

  • CTV

DYNAMIC_IDENTIFIER

23

  • Advertisements

Note

Use the “dynamic identifier” identifier type when eCST code is placed within an ad and macros are used in the iv parameter to capture more than one identifier type. An example of this would be a mixed mobile macro that could return an AAID or an IDFA depending on where the ad is run.

For example, the string to capture an AAID would look like this:

&it=5&iv=<daa3b324-bd4b-3c63-81e8-04f24290a3e>

Note

The tag will error if you use any value other than "5", "6", "17", "19", or "23" in the “it” field. For example, do not pass text, other integers, 0 or null values here. The tag will not error if plain text or null values are passed in the “iv” field. This would be the case if using macros that may not fire and cause either the macro text itself or a null value to be passed instead of the identifier.

Note

Only one identifier value may be passed in the “iv” field at a time.

Capturing Custom Data (pdata)

For implementations that include capturing custom data (pdata), see the “Capturing Custom Data (pdata)” section for more information on how to format the tag to capture custom data.

When using GET request methods, the custom data string must be URL encoded (the key-value pairs for custom data in POST implementations do not need to be URL encoded).

Note

For implementations where you do not want to include custom data: Leave out the pdata string ("&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>" in this example).

If you plan to use the tag to capture custom data (pdata), the POST method can be easier to implement. Because the pdata is passed as a JSON object in POST (rather than passing it through key/value pairs as part of the URL in GET), you avoid most formatting or URL-encoding issues for pdata with POST.

Note

If you are not capturing custom data (pdata) with the tag, then we do not recommend that you use the POST request method. However, the best method to use is largely dependent on the inventory that you will be capturing impressions on. Mixed methods can be used on campaigns if needed.

Use the format shown below when implementing the eCST tag via POST (formatting for the CST is similar).

https://di.rlcdn.com/api/segment?pid=<TAG ID>&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>

To test your tag from Terminal, you can use the following prompt:

curl -X POST https://di.rlcdn.com/api/segment?pid=<TAG ID>&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>\

-H 'Content-Type: application/json' -d '{"segments": {"<k1>": "<v1>", "<k2>": "<v2>"}}'

The following parameters are included in the tag example:

  • "<TAG ID>” is the tag ID ("pid") provided to you by LiveRamp

  • "<IDENTIFIER TYPE NUMBER>" is the number for the identifier type you want to capture, when capturing identifiers other than cookies (refer to the section on capturing additional identifiers below for the number to use)

  • "<IDENTIFIER VALUE>" is a valid value for the identifier specified in the "<IDENTIFIER TYPE NUMBER>" parameter

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

When using the POST request method to send pdata to LiveRamp, make sure to include quotation marks around “segments”, as well as every key and value (as shown in the testing example above).

Note

The example format shows a tag that has been configured to capture additional identifiers beyond cookies and to capture two key-value pairs of custom data. Modify the format to suit your use case:

  • To use the standard CST (when you only want to capture cookies), leave out the "&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>" string after the "<TAG ID>" parameter.

  • If you do not want to capture custom data (pdata), leave out the JSON object after the URL string, as shown in this testing example:

    curl -X POST \
    
    https://di.rlcdn.com/api/segment?pid=<TAG ID>&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>\

See the sections below for additional formatting information.

Capturing Additional Identifiers with the eCST

For each identifier (other than cookies) that you want to capture, include a string in the format "&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>" after the tag ID parameter (“pid=<TAG ID>”). Use the appropriate identifier type number shown in the table below.

Note

The eCST is currently in open beta for measurement use cases (our File-Based Recognition workflow, where log files are delivered back to you and/or a partner) and the use of the eCST requires an update to your contract. In the future, the eCST will also be available for activation use cases (where segments are created in your Connect account). Contact your LiveRamp representative for more information.

Identifier Type

Identifier Type Number

Applicable Environment(s)

AAID

5

  • In-app mobile

  • Advertisements

IDFA

6

  • In-app mobile

  • Advertisements

CONNECTED_TV_ID or

OTT_ID

17

  • OTT

  • CTV

IDENTITY_ENVELOPE

19

  • Web

  • Mobile web

  • In-app mobile

  • OTT

  • CTV

DYNAMIC_IDENTIFIER

23

  • Advertisements

Note

Use the “dynamic identifier” identifier type when eCST code is placed within an ad and macros are used in the iv parameter to capture more than one identifier type. An example of this would be a mixed mobile macro that could return an AAID or an IDFA depending on where the ad is run.

For example, the string to capture an AAID would look like this:

&it=5&iv=<daa3b324-bd4b-3c63-81e8-04f24290a3e>

Note

The tag will error if you use any value other than "5", "6", "17", "19", or "23" in the “it” field. For example, do not pass text, other integers, 0 or null values here. The tag will not error if plain text or null values are passed in the “iv” field. This would be the case if using macros that may not fire and cause either the macro text itself or a null value to be passed instead of the identifier.

Note

Only one identifier value may be passed in the “iv” field at a time.

Capturing Custom Data (pdata)

For implementations that include capturing custom data (pdata), see the “Capturing Custom Data (pdata)” section for more information on how to format the tag to capture custom data.

Note

If you are not capturing customer data (pdata) with the tag, we recommend that you do not use the POST request method.

For POST implementations, the key-value pairs for custom data are passed in a JSON object and do not need to be URL encoded (for GET implementations, the custom data string must be URL encoded).

Note

For implementations where you do not want to include custom data: Leave out the JSON object after the URL string. Your tag format would look like this:

curl -X POST \

https://di.rlcdn.com/api/segment?pid=<TAG ID>&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>\

During your implementation, LiveRamp will provide the following types of support:

  • We will provide you with the tag ID (pid).

  • For activation use cases, we will create the necessary additional audiences in your Connect account.

  • Once you configure the tag specific to your use case (including configure pdata) and provide the snippet to LiveRamp, we will verify whether the tag formatting looks good (key-value pairs, URL encoding, etc.).

  • After you've implemented the tag, we will confirm whether we are receiving data through the tag.

  • After you've implemented the tag, we will ensure that the pixel is delivering data as expected from our end.

Support Not Provided

LiveRamp does not provide the following types of support:

  • Implementing the tag on your site, in your tag manager, in your ad, in your email, etc.

  • Troubleshooting the tag implementation on your site, in your tag manager, in your ad, in your email, etc.

Note

We can't implement or troubleshoot the tag on your end for the following reasons:

  • We can't assume any liability regarding the functionality of your website (such as issues where the tag conflicts with another tag)

  • We don't know if you have any legal requirements based on your industry

  • This might require familiarity with your tag management suite (such as Adobe, Google Tag Manager, etc.)

Avoid the common implementation listed below.

Do Not Pass URLs as pdata

Do not pass URL strings as values in pdata when capturing custom data. 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.

Do Not Include Commas (",") or Equals Signs ("=") in pdata

When implementing the tag with pdata 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 equals 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.

See "Requirements for pdata" for more information.

Make Sure pdata is Formatted Correctly

If you're including pdata (custom data), make sure that it is constructed in key/value pairs, and that all keys have values. For example, something like "&pdata=visitor%3" in a GET implementation will not work because the key "visitor" has no corresponding value.

Also, make sure that the entire string after "pdata=" is URL-encoded in a GET implementation 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.

See below for answers to some common FAQs.

How can I URL encode values in pdata strings?

Make sure that the entire string after pdata= is URL-encoded in a GET implementation 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.

All letters (a-z, A-Z), numbers (0-9), dashes (-), underscores (_), dots (.), and tildes (~) can remain as is. Other symbols should be changed to their associated three-character string in the second row of the table below.

!

#

$

%

&

'

(

)

*

+

,

/

:

;

=

?

@

[

]

%21

%23

%24

%25

%26

%27

%28

%29

%2A

%2B

%2C

%2F

%3A

%3B

%3D

%3F

%40

%5B

%5D

Why do some impressions have strange or missing Ref-URLs?

It's important to note that LiveRamp does not set the Ref-URL. We simply read the value of the Referer HTTP header in the request that's made to our tag. This can be influenced by the Referrer-Policy that the website sets when it instructs the browser to make a request to our pixel server.

There are also Chrome extensions that allow users to obfuscate the Referer HTTP header with empty or confusing values. These extensions can also be set to spoof the Referer with a fake value, such as the address of the target server. In that case, we might see rlcdn.com populated as the Referer in requests to our pixel server.

Why might our impression volume numbers be different from LiveRamp's?

There will always be some discrepancy between the number of calls that you send versus the number of calls that LiveRamp's pixel server receives. There are multiple reasons this could be the case.

  • You might be serving impressions in an uncookieable environment. In this case, you are probably counting all impressions, whereas we are only counting the cookieable impressions.

  • If no cache buster is implemented, then a user's browser may cache our tag. In these cases, it may look to you like the tag was called, but the request was fulfilled locally by the user's browser and never actually reached our pixel server.

  • Something on the user's device or network, such as an ad blocker or firewall, prevented some requests from reaching our pixel server.

  • Users who have opted out will not be logged, but you will still see impressions for them.

  • You might be using a different time zone from LiveRamp, which uses UTC. If you are using any other time zone, your count of impressions for a particular date will be based on a different time frame from ours.

Why am I seeing a 451 error status when I try to call the tag?

LiveRamp's pixel server returns a 451 status code when a request is made from a country on the country exclusion list for that tag. If you are serving traffic from the EU, there will be special paperwork required, so please work with your account team to determine where you are allowed to use your tag if you believe this is necessary.

What's the best way to implement the tag?

There is no definitive answer to this question as it depends entirely on your technology stack, other partners you're working with, the outcome you're trying to accomplish, and so on. There are a large number of ways to implement a tag, and you should use the one that will work best for your use case. When in doubt, you should implement the CST or eCST as an image tag that uses GET requests.

Can LiveRamp remove some of the default fields or pdata from the output file?

Yes. Work with your LiveRamp representative to configure your file to remove the fields that you don't want to be included.