Implement the Enhanced Client-Side Tag
LiveRamp Client-Side Tags are tags that can be used to log user activities (such as page views or ad views, adding items to a cart, or completing a transaction) and then match the identifiers associated with those activities to RampIDs.
The Enhanced Client-Side Tag (eCST) tracks identifiers and can be placed in any cookieable environment (such as your website, marketing emails, or online advertisements), as well as in-app mobile, CTV, or OTT environments. The eCST can also track authentications on websites or mobile web apps by capturing identity envelopes containing RampIDs generated using LiveRamp's Authenticated Traffic Solution (ATS). You set the tag to fire on the desired user activity and the tag then logs these user activities into segments.
The enhanced Client-Side Tag (eCST) can collect the following identifiers:
LiveRamp cookies
Mobile device IDs (IDFAs and AAIDs)
Over The Top (OTT) and Connected TV (CTV) IDs
Identity envelopes (that contain RampIDs)
Note
If you only need to capture LiveRamp cookies on websites (including on mobile web) and in advertisements, use the standard Client-Side Tag (CST). For more information, see "Implement the Standard Client-Side Tag".
If you want to use the eCST to collect only LiveRamp cookies and identity envelopes, you can implement the eCST via an ATS integration module. For more information on this implementation method, see “Enhanced Client-Side Tag (eCST) for ATS for Web”. Otherwise, use the standard implementation method shown below.
If you use the tag to collect identity envelopes with a standard implementation method, you must base64 decode the envelope and then populate the envelope’s value into the eCST request. For more information, see the "Collecting Identity Envelopes in eCST Requests" section below.
If you have an existing CST that you want to upgrade to an eCST, see “Migrating From a CST to an eCST”.
The eCST automatically captures basic URL and log data by default, but additional custom data (“pdata”) can also be collected, depending on your needs. For more information, see “Data Automatically Captured” and “Capturing Custom Data (pdata)”.
The eCST can be used in two ways:
You can use the tag for measurement: The 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 (our File-Based Recognition Workflow). You can choose to receive one RampID for each identifier or to receive multiple RampIDs for each identifier (if there are more than one).
You can use the tag for activation: The segments can be automatically imported into your LiveRamp Connect account, where you can distribute them to your desired destinations (our Onboarding workflow).
Overview of Steps Involved
Once you've initiated the process with your LiveRamp representative, implementing the eCST involves the following steps:
You provide your LiveRamp Implementation team with the following information to begin the process of implementing the tag:
Note
If you’ve already gone through the implementation process but want to configure an additional CST or eCST, use one of the following Support Quick Case links to create a support case, depending on which workflow you’re using:
The types of user activity and environments you want to track, which determines the identifier types you'll be able to collect (for more information, see the "Identifier Types and Environments" section below.
Whether you want to capture additional custom data (pdata) beyond the data that tag captures automatically.
Note
You should plan on sending custom data (pdata). Without custom data, your log files will only contain a RampID and the automatically-collected data fields.
The countries you want to fire your eCST in.
Whether you plan to implement the tag as an image tag or iframe (for more information, see "Implementation Methods").
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 specify the location where you want the files to be delivered and whether you want to receive one file or separate files for each identifier type.
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).
You work with your technical team or tag manager to structure the tag properly to capture the desired data (for more information, see the section below on tag formatting).
You send an example of your tag to LiveRamp (e.g., "https://di.rlcdn.com/api/segment?pid=<TAG ID>"). If you are going to utilize the custom data (pdata) query parameter, make sure to send along examples of the eCST with populated custom data so that LiveRamp can ensure it’s formatted properly.
LiveRamp validates that the tag is formatted correctly and working as expected.
You work with your technical team or tag manager to implement the tag so that it fires on the desired user activity.
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 are then either delivered to you and/or your partner in batch files or used to create or update segments in your Connect account.
See the appropriate sections below for more information.
Format the Tag for GET Implementations
Once you've provided LiveRamp with the initial information and have received the tag ID, work with your technical team and tag manager to structure the tag properly.
Use the format shown below when implementing the eCST tag via GET and capturing custom data (pdata):
https://di.rlcdn.com/api/segment?pid=<TAG ID>&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>
Note
The example format shows a tag that has been configured to capture two key-value pairs of custom data (pdata). If you do not want to capture custom data (pdata), leave out the "
&pdata=<k1>%3D<v1>%2C<k2>%3D<v2>" string.For implementations that include capturing custom data, see "Capturing Custom Data (pdata)" for more information on how to format the tag to capture custom data and for the requirements for 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).
For information on populating the tag, see "Tag Example Parameters" and "Identifier Types and Environments" below.
If you’d like to do some basic testing of the tag from Terminal instead of implementing in your browser, 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>
Format the Tag for POST Implementations
Once you've provided LiveRamp with the initial information and have received the tag ID, work with your technical team and tag manager to structure the tag properly.
If you plan to use the tag to capture custom data (pdata), the POST method can be easier to implement. Because the pdata are 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 traffic 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:
https://di.rlcdn.com/api/segment?pid=<TAG ID>&it=<IDENTIFIER TYPE NUMBER>&iv=<IDENTIFIER VALUE>
For information on populating the tag, see "Tag Example Parameters" and "Identifier Types and Environments" below.
If you’d like to do some basic testing of the tag from Terminal instead of implementing in your browser, 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>"}}'Note
When using the POST request method to send pdata to LiveRamp, make sure to include quotation marks around segments and every key and value (as shown in the testing example above).
Tag Example Parameters
The following parameters are included in the tag examples:
"
<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 (for the number to use for each identifier type, see the "Identifier Types and Environments" section below)"
<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)
Identifier Types and Environments
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, depending on the environment(s) you're deploying the tag in.
Identifier Type | Identifier Type Number | Applicable Environment(s) |
|---|---|---|
AAID | 5 |
|
IDFA | 6 |
|
CONNECTED_TV_ID or OTT_ID | 17 |
|
IDENTITY_ENVELOPE | 19 |
|
DYNAMIC_IDENTIFIER | 23 |
|
Note
Use the “dynamic identifier” identifier type when eCST code is placed within an ad and macros are used in the
ivparameter 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.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.
Only one identifier value may be passed in the “iv” field at a time.
For example, the string to capture an AAID would look like this:
&it=5&iv=<daa3b324-bd4b-3c63-81e8-04f24290a3e>
Enhanced Client-Side Tag Usage and Examples for Different Environments
In addition to the web and mobile web environments where the standard CST can be used, the eCST can 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 |
|
In-App Mobile | No | Yes | No | Yes |
|
CTV or OTT | No | No | Yes | Yes |
|
Advertisements | Yes | Yes | Yes | No |
|
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>
Collecting Identity Envelopes in eCST Requests
When used in conjunction with ATS, eCST can enable better addressability on your Activation and Measurement use cases. When using both products together, identity envelopes are first base64 encoded before being saved to a first-party cookie.
In a standard implementation, this cookie must be base64 decoded, and subsequently you must parse out the envelope’s value and then populate the envelope’s value into the eCST request. If you do not base64 decode your identity envelopes, LiveRamp’s match processes will not be able to resolve them back to RampIDs.
For example, in the base64-decoded envelope shown below, the envelope value is shown after the “envelope” parameter:
{"timestamp":1665580740566,"version":"1.1.3","envelope":"AiLWLs8jYkz1PyFp8tZnd9AJ7ZFfksZ7gc5-rr9EPzd8tGQkEjS5fobLiBf2ovWMBvRCYkRcI-EBMO_4L5nlejCbXVwwOi6XuJ8yyeBNHhF2L-Dh8fWGZpvVTPuwjA5ISCPu"}
In this example, you would populate the eCST request with the envelope value AiLWLs8jYkz1PyFp8tZnd9AJ7ZFfksZ7gc5-rr9EPzd8tGQkEjS5fobLiBf2ovWMBvRCYkRcI-EBMO_4L5nlejCbXVwwOi6XuJ8yyeBNHhF2L-Dh8fWGZpvVTPuwjA5ISCPu.
Note
The other data contained in the decoded envelope (the Unix Timestamp of the creation of the envelope and the version of ATS.js you’re using) should not be included in your eCST request.