ATS
Guides

Pass PAIR IDs to the Bidstream

Suggest Edits

The Google PAIR integration with ATS Mobile SDK allows you to retrieve PAIR IDs along with an Identity Envelope.

You can leverage PAIR IDs in a mobile in-app environment, allowing in-app monetization with Google's DV360.

You do this by passing both identity envelopes and PAIR IDs into the bidstream.

You will typically pass the identity envelopes and PAIR IDs as a getter and setter method inside your in-app header bidder, or mediation SDK partner.

LiveRamp is working with several partners who support PAIR IDs in their SDKs which implementation shares the following key points:

  • You can provide both identity envelopes and PAIR IDs to these SDKs.
  • The SDKs pass those identity envelopes into their programmatic bidstreams.
  • The PAIR ID is bid on specifically by DV360; the identity envelope is bid on by everyone else.

🚧

Talk to Your LiveRamp Representative

Talk to your LiveRamp representative to discuss which solution will suit you best for passing your envelopes into the bid stream and how we can help you with monetizing.

Before You Begin

❗️

ATS Mobile SDK version 2.6.1 and above is required.

First, make sure that you can fetch identity envelopes through the getEnvelope method. To learn how, see the getEnvelope method for iOS and Android.

In the provided response object from getEnvelope, you can access the PAIR IDs with the following helper methods / properties:

Prebid (SDK)

Prebid offers an open-source solution for in-app mobile monetization. You can pass both identity envelopes and PAIR IDs from the ATS SDK to Prebid by adding those as ExternalUserId as illustratred below:

// Provide Identity Envelope as before
TargetingParams.storeExternalUserId(new ExternalUserId("liveramp.com", envelope, null, null));

// Add each PairID from the array
for (String pairId : pairIds) {  
// TODO: There is a known (minor) issue in Prebid where you are allowed only one PairID per source 
	TargetingParams.storeExternalUserId(new ExternalUserId("google.com", pairId, 571187, null));  
}


// Provide Identity Envelope as before
Targeting.shared.storeExternalUserId(ExternalUserId(source: "liveramp.com", identifier: envelope))

// Add each PairID from the array
for pairId in pairIds {        
// TODO: There is a known (minor) issue in Prebid where you are allowed only one PairID per source 
	Targeting.shared.storeExternalUserId(ExternalUserId(source: "google.com", identifier: pairId, atype: 571187))
}

For more information on how to set ExternalUserId within Prebid for in-app, see the Prebid SDK documentation for iOS or Android SDK.

Pubmatic

❗️

LiveRamp requires Pubmatic OpenWrap SDK support for setting Atype

Work with your Pubmatic account manager to ensure you have the latest iOS/Android SDK in your existing application.

Pubmatic allows in-app publishers to pass identity envelopes from the ATS SDK to configured OpenWrap partners through the OpenWrap SDK. See below to learn how you can pass identity envelopes and PAIR IDs to Pubmatic's OpenWrap SDK:

// Set the envelope you get from ATS Mobile SDK here
POBExternalUserId envelopeId = new POBExternalUserId("liveramp.com", envelope);

// Add the ID to OW SDK 
OpenWrapSDK.addExternalUserId(envelopeId);


// Add each PairID from the array
for (String pairId : pairIds) {  
	POBExternalUserId tPairID = new POBExternalUserId("google.com", pairId);  
	tPairID.setAtype(571187);  
	OpenWrapSDK.addExternalUserId(tPairID);  
}


// Set the envelope you get from ATS Mobile SDK here
let userId = POBExternalUserId(source: "liveramp.com", andId: envelope)
 
// Add the ID to OW SDK 
OpenWrapSDK.addExternalUserId(userId)

// Also add each PairID from the array
for pairId in pairIds {
    let tPairId = POBExternalUserId(source: "google.com", andId: pairId)
    tPairId.atype = 571187;
    OpenWrapSDK.addExternalUserId(tPairId)
}

Nimbus

❗️

LiveRamp requires Nimbus SDK support for setting the Atype

Work with your Nimbus account manager to ensure you have the latest Nimbus iOS/Android SDK in your existing application.

Nimbus's SDK allows you to pass both identity envelopes and PAIR IDs to Nimbus' exchange.

There are two ways you can do this:

  1. By using the ATS Mobile SDK to generate identity envelopes and PAIR IDs and pass both of them to Nimbus:

    // Set the envelope you get from ATS Mobile SDK here
HashMap<String, String> extMap = new HashMap<String, String>();  
extMap.put("rtiPartner", "idl");  
  
NimbusAdManager.addExtendedId("liveramp.com", envelope, extMap);


Set<UID> tPairIDSet = new HashSet<UID>();  

// Add each PairID from the array
for (String pairId : pairIds) {  	
	UID tPairID = new UID(pairId, 571187, new HashMap<>());  
	tPairIDSet.add(tPairID);  
}  
  
EID nimbusPairEids = new EID("google.com", tPairIDSet);  
NimbusAdManager.getExtendedIds().add(nimbusPairEids);


    // Add LiveRamp Envelope
  NimbusAdManager.addExtendedId(
        source = "liveramp.com",
        id = envelope,
        extensions = mapOf("rtiPartner" to "idl"),
  )

  // Add PairIDs
  NimbusAdManager.extendedIds.add(
    EID(
        source = "google.com",
        uids = setOf(UID(id = pairId, atype = 571187)),
    )
)



    var extendedId = NimbusExtendedId(source: "liveramp.com", id: envelope)
extendedId.extensions = ["rtiPartner": NimbusCodable("idl")]

/* Setting extendedIds more than once will clear the previous results and is nil by default */
NimbusAdManager.extendedIds = [extendedId]

// Add each PairID from the array
for pairId in pairIds {
    NimbusRequestManager.extendedIds?.insert(
    NimbusExtendedId(source: "google.com", uids: [NimbusExtendedId.UID(id: pairId, atype: 571187)])
)}

  2. By using the Nimbus-LiveRamp extension to generate and pass identity envelopes along with PAIR IDs to the bidstream. If you prefer this method, talk to your Nimbus account manager so they can set it up for you. See Nimbus' documentation for iOS and Android for more information.

Updated over 1 year ago