Implementing LiveRamp’s Client Side Tag

The LiveRamp Client Side Tag is a tag that can be placed on any cookieable website, or in any email or online advertisement. It is used to log impressions, group them into segments, and automatically import those segments into LiveRamp for processing. The tag can also be set up to redirect the user to a new URL after data is captured.

How it works:

  1. LiveRamp provides you with a tag ID.

  2. You work with your technical team or tag manager to implement the tag, which involves inserting the provided tag ID into the basic tag format shown in the "Formatting the Client Side Tag" section below. (You can also capture additional custom data through pdata, if desired).

  3. LiveRamp validates that the tag is working as expected.

  4. Once the segments have been ingested, LiveRamp can deliver the impression data back to you directly or you can distribute them to your desired destinations.

See the appropriate sections below, including "Avoiding Common Implementation Issues", for more information.

Contact your LiveRamp representative to begin the process of implementing a Client-Side Tag.

Some common use cases for Client Side Tags include:

  • Tracking browsing behavior on websites

  • Building segments based on online purchase behavior in real time

  • Building segments out of ad or email impressions for measurement and retargeting

The Client Side Tag automatically captures basic URL and log data by default, but additional data can also be captured, depending on your needs. See the “Capturing Custom Data” section of this document for more information.

Client Side Tags can also be implemented so that they redirect the user to a different URL after capturing data. See the “Utilizing the Redirect Option” section of this document for more information.

Client Side Tags can be implemented via iframe or gif. See the "Formatting the Client Side Tag" section of this document for specific formatting information.

Once a day (at 0:00 UTC time), LiveRamp generates log files containing all data logged from the Client Side Tag in the previous day, and then ingests that data.

By default, the following data is automatically captured and stored as segments (with the field names listed below) in LiveRamp for all tags:

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

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

    Note

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

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

Caution

Don't include these data types in custom data: Since this data is captured by default, there is no need to add this type of information as custom data in your tag.

Note

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.

Once your LiveRamp rep has provided you with your tag ID, use the basic tag format shown below, depending on how you’re implementing the Client Side Tag:

  • For implementation via iframe (without pdata):

    <iframe name="_rlcdn" width=0 height=0 frameborder=0 
    src="https://di.rlcdn.com/<TAG ID>.html"></iframe>
  • For implementation via gif (without pdata):

    <img style="display: none;" src="https://di.rlcdn.com/<TAG ID>.gif"/>
  • For implementation via iframe (with pdata):

    <iframe name="_rlcdn" width=0 height=0 frameborder=0
    src="https://di.rlcdn.com/<TAG ID>.html?pdata=<PDATA>"></iframe>
  • For implementation via gif (with pdata):

    <img style="display: none;" src="https://di.rlcdn.com/<TAG ID>.gif?pdata=<PDATA>"/>

For all implementations: The “<TAG ID>” string must be replaced with your specific tag ID. See the “Inserting Your Tag ID” section of this document for more information.

For any implementations where you want to capture custom data: The “<PDATA>” string must be replaced with pdata information. Note: Only include a pdata string, and the string “?pdata=”, if additional custom data is desired. See the “Capturing Custom Data” section of this document for more information.

For any implementations where you want to redirect the user to a different URL: See the “Utilizing the Redirect Option” section of this document for more information.

LiveRamp uses the tag ID to recognize the owner of the tag and ingest the data into the correct LiveRamp Connect account. Each tag has its own distinct tag ID. Your LiveRamp representative will provide you with the appropriate tag ID for each tag you implement.

Replace “<TAG ID>” in the formatting examples with the tag ID given to you by your LiveRamp representative.

You can capture custom data, in addition to the data that is captured automatically, by utilizing pdata in your pixel. Pdata is optional, key-value segment data that is sent to LiveRamp with the impression.

You can configure any desired information that is within our privacy guidelines to be passed as pdata. If a tag contains pdata, impressions captured via that tag will be placed into key-value segments associated with that pdata in Connect.

Caution

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>” string shown in the formatting examples; your pixel URL will stop after ".html" or ".gif").

Requirements for pdata

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

  • Make sure that the pdata contains at least one key/value pair. That is, "https://di.rlcdn.com/401576.gif?pdata=" is not allowed.

    Note

    If you are not using pdata to capture custom data, remove "?pdata=" from the URL.

  • Make sure that all keys have values. That is, something like "key1=" is not allowed.

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

  • For a given key to support enumerated segments (both within Connect or in LiveRamp's systems in general), do not pass more than 100 distinct values per key.

  • A minimum of 25 devices must populate each segment (e.g., if "Gender=Male" is the segment being populated, there needs to be at least 25 devices in that segment). This is a privacy requirement.

  • Make sure that all values have keys. That is, something like "=value1" is not allowed.

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

  • Do not include commas or equals signs in keys or values, as this results in incorrect parsing of the data. See the “Replacing Commas and Equals Signs in pdata Keys and Values” section of this document for more information.

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

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

Warning

Requirements must be followed: Any pixel 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.

Tag Example Using pdata

Here is an example of a tag using pdata to capture the custom data “visitor=yes” and “category=home” in an iframe after the pdata string has been URL-encoded per the requirements:

<iframe name="_rlcdn" width=0 height=0 frameborder=0 
src="https://di.rlcdn.com/401576.html?
pdata=visitor%3Dyes%2Ccategory%3Dhome">< /iframe>

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: https://meyerweb.com/eric/tools/dencoder/).

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

  • visitor = yes        

  • category = home

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

Optionally, you can enable the Client Side Tag so that it redirects the user to a different URL after capturing data. All redirect URLs must be whitelisted by LiveRamp, so you must provide us with a list of the URLs you want to include in the whitelist. We tie this whitelist to your tag ID and will only redirect traffic to URLs that have been included in the whitelist.

Subdomains will be included in the whitelisting. For example, if you whitelist “mywebsite.com” any subdomains to that site (such as “mywebsite.com/sale” or mywebsite.com/new”) will also be whitelisted.

Caution

Make sure to URL encode! The whitelisted URL must be URL-encoded in the tag.

This also requires different tag formatting, as shown below for iframe and gif implementations.

  • For implementation via iframe:

    <iframe name="_rlcdn" width=0 height=0 frameborder=0 
    src="https://di.rlcdn.com/<TAG ID>.html?pdata=<PDATA>&credir=https%3A%2F%2F<WHITELISTED URL>"></iframe>
  • For implementation via gif:

    <img style="display: none;" src="https://di.rlcdn.com/<TAG ID>.gif?pdata=<PDATA>&credir=https%3A%2F% 2F<WHITELISTED URL>"/>

Test the Redirect

Once you have your tag ID and your URL whitelist has been accepted, we recommend you first test your redirect without pdata and with just the base URL (no subdomains) by pasting the redirect in a browser (template below). If you are routed to the whitelisted URL then your redirect is working. From there we recommend you add in your pdata and again check that you are redirected to your destination URL when you test in a browser.

  • Template for testing redirects in browser without pdata:

    di.rlcdn.com/<PIXEL ID>.gif?credir=https%3A%2F%2F<WHITELISTED URL>
  • Template for testing redirects in browser with pdata:

    di.rlcdn.com/<PIXEL ID>.gif?pdata=<PDATA>&credir=https%3A%2F%2F<WHITELISTED URL>

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.

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

LiveRamp’s clients do successfully leverage Client Side Tags (with and without redirects) 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.

Avoid the common implementation listed below.

Passing URLs as pdata

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.

Including Commas (",") or Equals Signs ("=") in pdata

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.