Server-to-Server Implementation for Google PAIR

If you implement ATS through server-to-server integration, you can integrate Google PAIR using the method in this article to send PAIR IDs to your downstream partners. This method is suitable for you if you and your partners participate in OpenRTB (Open Real-Time Bidding) and already pass identity envelopes to downstream bid requests directly.

1. Enable Google PAIR

You'll need to contact a LiveRamp representative to get Google PAIR activated for a desired ATS placement. Once activated, the ATS envelope response should contain an Identity Envelope together with one or more PAIR IDs.

2. Retrieve Envelopes Together with PAIR IDs

After preparing the email or phone number identifiers, you can call the ATS Envelope API as you normally would. When calling the 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.

🚧

Server-to-Server Integrations

When retrieving or refreshing the ATS Envelopes, publishers integrating server-to-server are required to include the X-Forwarded-For header to ensure that the client-side IP address is within the approved countries tied to the ATS Placement.

For example:

cURL

curl --request GET \
     --url 'https://api.rlcdn.com/api/identity/v2/envelope?pid=14&it=4&iv=38CFDA7F9B55B7F74B6D3D143CBB7661DA9BFEB4683473A5813B220A571A1E37&ct=4&cv=CPUCbs9PUDXghADABCENCBCoAP_AAEJAAAAADGwBAAGABPADCAY0BjYAgADAAngBhAMaAAA.YAAAAAAAA4AA' \
     --header 'Origin: https://example.com' \
     --header 'X-Forwarded-For: 203.0.113.195' \
     --header 'accept: application/json'

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. Parse the PAIR ID

1. In your envelope response, look for the pairids key which should look like the following:

{
   "type": 25,
   "source": "pairIds",
   "value": "WyJBeVhiNUF0dmsvVS8xQ1d2ejJuRVk5aFl4T1g3TVFPUTJVQk1BMFdiV1ZFbSJd",
   "err": null
}

2. Take the entire pairIds value object and Base64 decode it. From the above response, the entire value object is the following:
   WyJBeVhiNUF0dmsvVS8xQ1d2ejJuRVk5aFl4T1g3TVFPUTJVQk1BMFdiV1ZFbSJd
   After Base64 decoding, it should yield a JSON string which looks like the following:
   '["AyXb5Atvk/U/1CWvz2nEY9hYxOX7MQOQ2UBMA0WbWVEm"]'
3. Parse the JSON string with your library or tool of choice. Note that the array may contain multiple PAIR IDs.
   AyXb5Atvk/U/1CWvz2nEY9hYxOX7MQOQ2UBMA0WbWVEm
   Make sure all pairIds are appropriately stored and you can retrieve them to ensure your monetization is not affected.

Storing PAIR IDs

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 store your PAIR ID and identity envelopes along with a timestamp.
With timestamps in place, you can more easily determine if the identity envelope and PAIR ID need to be refreshed when it exceeds the refresh period.

4. Refresh the PAIR IDs

You must use the associated identity envelope to refresh a PAIR ID. To refresh PAIR IDs, call the envelope refresh API using a regular ATS envelope. The ATS API response will contain a new identity envelope and 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.

🚧

• If a PAIR ID was generated in a different region, you must call the ATS Envelope API again to produce a new PAIR ID specific to the new region. Calling the ATS Envelope Refresh API in this case will only return an identity envelope.
• 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 with a new timestamp.

5. Send PAIR IDs in Downstream Requests

You must send both the PAIR IDs and the Identity Envelope to your downstream partners. The example below illustrates how you can do this with the ext.eids field within the OpenRTB protocol.

"user": {
    "ext": {
      "eids": [        
        {
          "source": "liveramp.com",
          "uids": [
            {
              "id": "AvxfXjwFaie3SW…",
              "atype": 3
            }
          ]
        },
        {
          "source": "google.com",
              {
              "id": "AGgIhrPMirF..",
              "atype": 571187
            }
          ]
        }...

📘

Test and Verify

Talk to a LiveRamp representative and present them a network trace or logs of your OpenRTB requests to one or multiple programmatic partners.