ATS
Guides

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&atype=2

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":"Aqs3wtOuqIRic78_s4Nqilcr0MGn0cDvKzvpEhSGVjwV8Ci0Jy73B1bkfpv03GwK2uyKbME4kSAtVFn_5sCLWstyHTnEWYurbjLXLpgtf9MfLP1AeDTUQ_0ESnD3x1pr6gYfBOOUH8BPhbfscxdaGUA-_sacPab3nzc05koLhbqrJIQC7JBraEbpOJPDAHp9f44DXIXm","err":null},{"type":25,"source":"pairIds","value":"WyJBeVhiNUF0dmsvVS8xQ1d2ejJuRVk5aFl4T1g3TVFPUTJVQk1BMFdiV1ZFbSJd","err":null}]}

3. Store the PAIR IDs

In this scenario, we are storing the PAIR ID from the below response. Note the pairIds value object that contains a base64-encoded PAIR ID which is 64 characters in length.

{"envelopes":[{"type":19,"source":"envelopeLiveramp","value":"Aqs3wtOuqIRic78_s4Nqilcr0MGn0cDvKzvpEhSGVjwV8Ci0Jy73B1bkfpv03GwK2uyKbME4kSAtVFn_5sCLWstyHTnEWYurbjLXLpgtf9MfLP1AeDTUQ_0ESnD3x1pr6gYfBOOUH8BPhbfscxdaGUA-_sacPab3nzc05koLhbqrJIQC7JBraEbpOJPDAHp9f44DXIXm","err":null},{"type":25,"source":"pairIds","value":"WyJBeVhiNUF0dmsvVS8xQ1d2ejJuRVk5aFl4T1g3TVFPUTJVQk1BMFdiV1ZFbSJd","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:
    WyJBeVhiNUF0dmsvVS8xQ1d2ejJuRVk5aFl4T1g3TVFPUTJVQk1BMFdiV1ZFbSJd
    After decoded from Base64, the PAIR IDs will be 44 characters in length, as shown below:
    ["AyXb5Atvk/U/1CWvz2nEY9hYxOX7MQOQ2UBMA0WbWVEm"]
  2. Modify the result so it contains the envelope object.
    {"envelope":["AyXb5Atvk/U/1CWvz2nEY9hYxOX7MQOQ2UBMA0WbWVEm"]}
  3. Encode the entire string to Base64 format:
    eyJlbnZlbG9wZSI6WyJBeVhiNUF0dmsvVS8xQ1d2ejJuRVk5aFl4T1g3TVFPUTJVQk1BMFdiV1ZFbSJdfQ==
  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.

We recommend storing a timestamp next to your PAIR ID so you can easily determine if the PAIR ID needs to be refreshed when it exceeds the refresh period.

See the example below for setting a timestamp for first-party cookies and local storage. Based on the user's 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 Header-Bidding Implementation

Follow the instructions below based on which header-bidding solution you are running to ensure to ensure PAIR IDs are picked up and passed to downstream bidders:

  • Prebid: 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.
  • Amazon TAM: No additional action is required within the Amazon UI for PAIR IDs to be picked up and passed. This will happen automatically.
  • FreeWheel: You can pass PAIR IDs to MRM in the ad request using the reserved key-value _fw_3P_uid. The value passed should be in the format PAIRID:UseridValue. Contact your Freewheel's representative for more information.

Updated 8 months ago