ATS

Google PAIR

Suggest Edits

PAIR (Publisher Advertiser Identity Reconciliation) is a framework that Google Display & Video 360 has developed to facilitate a secure and privacy-focused way for enabling advertisers and publishers to match their first-party data for marketing use cases via advanced data encryption methods without the reliance on third-party cookies.

1. Enable Google PAIR

You must contact a LiveRamp representative to get Google PAIR enabled for a desired ATS placement. Once enabled, when making a call to retrieve ATS envelopes the response may contain an identity envelope together with one or more PAIR IDs.

2. Retrieve ATS Envelopes Together with PAIR IDs

🚧

ATS API V2 Endpoint Required

To retrieve PAIR IDs, you are required to create requests using the ATS API version 2 endpoint. For example:
https://api.rlcdn.com/api/identity/v2/envelope?pid=999&it=4&iv=3e33f1163236952e4fe8ea00ead7b8a2e65a75b694a462b14ef6b71d1913d89f&it=4&iv=939a10fa43251d6eaa21181c2d124435eca00e2f&it=4&iv=78200486ad9e3264708fd1fb36b5941d

See our announcement to learn more.

After preparing the email or phone number identifiers, you can call the ATS envelope API as you normally would. When calling the ATS Envelope API with a PAIR-enabled placement, multiple identity envelopes can be returned; one is a regular ATS envelope and the other is a Base64-encoded string of one or multiple PAIR IDs.

An example of a response containing PAIR IDs is as follows:

{"envelopes":[{"type":19,"source":"envelopeLiveramp","value":"Alkc6LgKZzbqHvexyq4hyzxp0zQZnIztut2rFKjmcDtSBbM0rttk5pH2qb8iNkyxCO9kYAKg6oM2rt28dbWV6-lt9BxwoPCabDaOUXN3fr2C1qsCeV9H0qcW3wBPbbnTpxFWI0Wnh7WVPFYrCM8FgziDEBwSoYnUMO9wheayikvFSGX3Qsz1lr0QWnj2dHEMhx5V2QEbhkJ2iwH2zLEaKAt5oVa8EwAf59mOQepN3S_CwQk4C5OkgfZYiUXTYwxpDA","err":null},{"type":25,"source":"pairIds","value":"WyJ6SU5BVGppTGpaUUJITTNENUtvcUoweTNYdFlsNDZVaDN4bW5aUm9OYlNNSyIsIlllR3MyUTR6eG5Ba0x3b05leDlxSm9vRFhPb3NndUloV1dPWGdITVhFZ0ZtIiwiQXBMdS83OEt0UlkzSnFrdEdUT0JTZkVjclczRWo0b0VWaE16Y1VtRDZ4M2ciLCJBdDBTVlBZalBiMUd4UjlGSFd0SS9xWFFINTRXUFllSTlWelc5MTRFWHJ4VSJd","err":null}]}

3. Store the PAIR IDs

In this scenario, we are storing the PAIR ID from the below response.

{"envelopes":[{"type":19,"source":"envelopeLiveramp","value":"Alkc6LgKZzbqHvexyq4hyzxp0zQZnIztut2rFKjmcDtSBbM0rttk5pH2qb8iNkyxCO9kYAKg6oM2rt28dbWV6-lt9BxwoPCabDaOUXN3fr2C1qsCeV9H0qcW3wBPbbnTpxFWI0Wnh7WVPFYrCM8FgziDEBwSoYnUMO9wheayikvFSGX3Qsz1lr0QWnj2dHEMhx5V2QEbhkJ2iwH2zLEaKAt5oVa8EwAf59mOQepN3S_CwQk4C5OkgfZYiUXTYwxpDA","err":null},{"type":25,"source":"pairIds","value":"WyJ6SU5BVGppTGpaUUJITTNENUtvcUoweTNYdFlsNDZVaDN4bW5aUm9OYlNNSyIsIlllR3MyUTR6eG5Ba0x3b05leDlxSm9vRFhPb3NndUloV1dPWGdITVhFZ0ZtIiwiQXBMdS83OEt0UlkzSnFrdEdUT0JTZkVjclczRWo0b0VWaE16Y1VtRDZ4M2ciLCJBdDBTVlBZalBiMUd4UjlGSFd0SS9xWFFINTRXUFllSTlWelc5MTRFWHJ4VSJd","err":null}]}

To store the PAIR ID:

  1. Take the entire pairIds value object and decode from Base64 format. From the above response, the entire PAIR value object is the following:
    WyJ6SU5BVGppTGpaUUJITTNENUtvcUoweTNYdFlsNDZVaDN4bW5aUm9OYlNNSyIsIlllR3MyUTR6eG5Ba0x3b05leDlxSm9vRFhPb3NndUloV1dPWGdITVhFZ0ZtIiwiQXBMdS83OEt0UlkzSnFrdEdUT0JTZkVjclczRWo0b0VWaE16Y1VtRDZ4M2ciLCJBdDBTVlBZalBiMUd4UjlGSFd0SS9xWFFINTRXUFllSTlWelc5MTRFWHJ4VSJd
    After decoding from Base64, it should look like:
    ["zINATjiLjZQBHM3D5KoqJ0y3XtYl46Uh3xmnZRoNbSMK","YeGs2Q4zxnAkLwoNex9qJooDXOosguIhWWOXgHMXEgFm","ApLu/78KtRY3JqktGTOBSfEcrW3Ej4oEVhMzcUmD6x3g","At0SVPYjPb1GxR9FHWtI/qXQH54WPYeI9VzW914EXrxU"]
  2. Modify the result so it contains the envelope object.
    {"envelope":["zINATjiLjZQBHM3D5KoqJ0y3XtYl46Uh3xmnZRoNbSMK","YeGs2Q4zxnAkLwoNex9qJooDXOosguIhWWOXgHMXEgFm","ApLu/78KtRY3JqktGTOBSfEcrW3Ej4oEVhMzcUmD6x3g","At0SVPYjPb1GxR9FHWtI/qXQH54WPYeI9VzW914EXrxU"]}
  3. Encode the entire string to Base64 format:
    eyJlbnZlbG9wZSI6WyJ6SU5BVGppTGpaUUJITTNENUtvcUoweTNYdFlsNDZVaDN4bW5aUm9OYlNNSyIsIlllR3MyUTR6eG5Ba0x3b05leDlxSm9vRFhPb3NndUloV1dPWGdITVhFZ0ZtIiwiQXBMdS83OEt0UlkzSnFrdEdUT0JTZkVjclczRWo0b0VWaE16Y1VtRDZ4M2ciLCJBdDBTVlBZalBiMUd4UjlGSFd0SS9xWFFINTRXUFllSTlWelc5MTRFWHJ4VSJdfQ==
  4. Take the encoded string and store it in a first-party cookie or local storage called _lr_pairId.

4. Store the PAIR IDs TTL

To be GDPR and CCPA compliant, PAIR IDs are generated with a 15-day TTL ("Time to Live" / expiration time) for California (U.S.) and a 30-day TTL for all other countries and regions.

To avoid passing expired PAIR IDs that cannot be decrypted by Google APIs, we recommend you to store a timestamp next to your PAIR ID. With timestamps in place you can more easily determine if the PAIR ID needs to be refreshed when it exceeds the refresh period.

We’ve provided an example below for setting a timestamp for first-party cookies and for local storage. Based on the users geo location you will need to set the correct expiration time.

In the example below, we use the first party cookie _lr_pairId_exp and the local storage key name _lr_pairId_exp:

function calculatePairTTL(countryCode, regionCode) {
  let expirationTime = 2592000000;
  if (countryCode === 'US') {
    if (regionCode === 'CA') {
      expirationTime = 1296000000;
    }
  }
  expirationTime += +new Date();
  return expirationTime;
}

// Example: set a cookie to track envelope expiration in 15 days
document.cookie = '_lr_pairId_exp=' + calculatePairTTL('US', 'CA');

// Example: set a cookie to track envelope expiration in 30 days
document.cookie = '_lr_pairId_exp=' + calculatePairTTL();  

// Example: set localStorage to track envelope expiration for 15 days
localStorage.setItem('_lr_pairId_exp' , calculatePairTTL('US', 'CA');

// Example: set localStorage to track envelope expiration for 30 days
localStorage.setItem('_lr_pairId_exp' , calculatePairTTL());

You can then read out the appropriate timestamp like so for cookies:

// Example helper function to get cookie by name
function getCookieValue(cookieName) {
   cookieName += "=";
   var tCookieArr = document.cookie.split(';');
    for (var i = 0; i < tCookieArr.length; i++) {
     var tCookie = tCookieArr[i].trim();
 
     if (tCookie.indexOf(cookieName) === 0) {
       var cookieVal = tCookie.substring(cookieName.length, tCookie.length)
       return decodeURIComponent(cookieVal);
     }
   }
    return "";
}
 
getCookieValue("_lr_pairId_exp");
/* Then, call the Envelope Refresh API as required */

And for local storage:

localStorage.getItem("_lr_pairId_exp");
/* Then, call the Envelope Refresh API as required */

5. Refresh the PAIR IDs

We highly recommend calling the Refresh Envelope API on the first subsequent page load after a user authenticates and again every 30 minutes when a user enters a new page or refreshes the current page.

To refresh PAIR IDs you need to call the envelope refresh API using a regular ATS envelope. The ATS API response will contain new PAIR IDs that can replace the old ones. 

https://api.rlcdn.com/api/identity/v2/envelope/refresh?pid=[placement id]&it=[envelope type]&iv=[envelope value]&ct=[consent type]&cv=[consent string]

To learn more, see Implement the ATS Refresh Envelope API.

🚧

When you refresh PAIR IDs, don't forget to replace the old PAIR IDs with new ones in the storage. You must also update the PAIR TTL cookie with a new timestamp.

6. Configure Your Prebid.js Implementation

If you are using Prebid to pass PAIR IDs to the bidstream, you must include the Google Pair ID Module in your Prebid configuration to make sure PAIR IDs are included in ad requests. To learn more, see Implement Prebid.js for ATS.

Updated 12 months ago