ATS

Pass Envelopes to the Bidstream

Suggest Edits

Once your ATS Mobile SDK is up and running, you want to be able to monetize the Identity Envelopes. You can do this by passing them into the bid stream as an ad request for your header bidder SDK or ad partner.

LiveRamp is working with several partners that support such integration and presently pass our envelopes in the bid stream. See the instructions below based on the partner you are working with.

🚧

Talk to Your LiveRamp Representative

If you haven't yet, 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

You must fetch Identity Envelopes using getEnvelope before passing them to a partner.

Identity envelopes have a TTL (time to live) of 15 days, after which they will become invalid. By using the getEnvelope method, the SDK will ensure that you are always passing an up-to-date value to better help you monetize.

Learn more about the getEnvelope method for iOS and Android.

Prebid (SDK)

You can pass envelopes to Prebid server for iOS/Android SDK by adding the envelope as an ExternalUserId:

externalUserIdArray.add(new ExternalUserId("liveramp.com", "<liverampEnvelope>", null, null));

externalUserIdArray.append(ExternalUserId(source: "liveramp.com", identifier: "<liverampEnvelope>"))

For more information, see the Prebid SDK documentation for iOS or Android SDK.

InMobi

InMobi allows in-app publishers to pass envelopes into the bid stream using their UnifID service. There are two ways you can pass envelopes to InMobi:

  • (Recommended) Use the ATS Mobile SDK to generate the envelopes and pass them to InMobi's UnifID service using setPublisherProvidedUnifiedId. 
val unifiedIds = JSONObject().put("liveramp.com", envelope)
InMobiSdk.setPublisherProvidedUnifiedId(unifiedIds)

var idDictionary = ["liveramp.com": envelope]
IMSdk.self.setPublisherProvidedUnifiedId(idDictionary)
  • Use InMobi’s own SDK to generate and pass envelopes. See InMobi's SDK Specifications to learn how.

Pubmatic

❗️

LiveRamp requires Pubmatic OpenWrap SDK V2.5.0 and above

Work with your Pubmatic Account Manager to ensure you have the latest Nimbus iOS/Android SDK in your existing application.

If you are working with Pubmatic, you can pass envelopes through Pubmatic OpenWrap SDK after implementing the ATS Mobile SDK.

To set up the Pubmatc integration:

  1. Implement the ATS Mobile SDK for iOS or Android. Make sure you keep the Config ID (appID) that you generated in Console at the beginning of implementation.
  2. Pass the envelopes obtained from the ATS Mobile SDK to Pubmatic. See the following documentation in Pubmatic's portal (login to Pubmatic required) or check out the example below: 
// Set the envelope you get from ATS Mobile SDK here
// It MUST be liveramp.com to work
var userId = POBExternalUserId(source: "liveramp.com", andId: "<liverampEnvelope>")
 
 
// Add the ID to OW SDK 
OpenWrapSDK.addExternalUserId(userId)

// Set the envelope you get from ATS Mobile SDK here
// It MUST be liveramp.com to work
POBExternalUserId adServerUserId = new POBExternalUserId("liveramp.com","<liverampEnvelope>");


// Add the ID to OW SDK 
OpenWrapSDK.addExternalUserId(adServerUserId);
  1. Verify that an envelope is being used in an ad request. Look for the POST request from https://ow.pubmatic.com/openrtb/2.5 and verify that the envelope is present under user.ext.eids.uids. If everything is correct, you should also see liveramp.com as the "source". See the example below:
1162

Nimbus

❗️

LiveRamp requires Nimbus SDK V2.1.0 and above

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

Nimbus SDK allows you to pass envelopes to Nimbus' exchange. There are two ways you can do this:

  • Use the ATS Mobile SDK (or another partner) to generate envelopes and pass the envelopes to Nimbus SDK. For example:

    /** Returns true if the ID was successfully added */
fun addLiveRampId(envelope: String) = NimbusAdManager.addExtendedId(
      source = "liveramp.com",
      id = envelope,
      extensions = mapOf("rtiPartner" to "idl"),
)

    func addLiveRampId(envelope: String) {
    /* Create NimbusExtendedId */
    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]
}

    Then, using a proxy tool, look for the Nimbus ad request (which is a OpenRTB request) and verify the LiveRamp envelope is present under user.ext.eids.uids. If everything is correct, you should also see liveramp.com as the "source". See the example below:

🚧

To learn more about the iOS version of this feature, get in touch with your Nimbus Account Manager.

  • Use the Nimbus-LiveRamp extension to generate and pass envelopes. If you implement this option, no additional call to pass the envelopes is required. For more information, see Nimbus' documentation for Android and iOS.

MobileFuse

🚧

Work with your MobileFuse Account Manager to ensure that you have the latest MobileFuse iOS or Android SDK in your existing application.

To pass the envelopes to MobileFuse Exchange (MFX), call the MobileFuse SDK: 

// Pass in a RampID Envelope here
[MobileFuseTargetingData setLiveRampEnvelope: @"<liverampEnvelope>"];

// Pass in a RampID Envelope here
MobileFuseTargetingData.setLiveRampEnvelope(“<liverampEnvelope>”)

Then you can use an MITM proxy tool to verify that the Identity Envelope is set properly in the MobileFuse SDK. Look for the MobileFuse MFX ad request (which is an openRTB request) and verify that the LiveRamp envelope is present under user.ext.eids.uids. If everything is correct, you should also see liveramp.com as the "source". For example:

{
    "user": {
        "ext": {
            "eids": [{
                "source": "liveramp.com",
                "uids": [{
                    "id": "AvAPLiE-oU_cYmbXgyM0YCOXEnRg489A51pX2uvjoZx5f8V_1yzB_nkAQ5wICpnk2s_Iw1MvC0DL2sqkbzbtJSbEy9IWp5AYnJcL"
                }]
            }, {
                "source": "uidapi.com",
                "uids": [{
                    "id": "AgAAAAPHpn5cHG8VyP6CAuHh5AMemVXXXxMdVzjhmdRl0nt8cglqmMRWTmKap05HIeNpLvEaAERX2mLp0RVSJz0M48igDHx53dsrnaenCAG/VDTJcAkHFLIplzOFjYASu0wtXsJ3IBNAWjSABjs7xmEXq73B16HRZAeCCBBKGBdvhp0rww=="
                }]
            }]
        }
    }
}

AppLovin MAX (SDK)

You can pass envelopes to AppLovin MAX for the iOS/Android SDK by adding the envelope as an extra parameter in AppLovinSdkSettings:

AppLovinSdkSettings settings = AppLovinSdk.getInstance( context ).getSettings();
settings.setExtraParameter( "liveramp.com", "<liverampEnvelope>" );

let settings = ALSdk.shared()?.settings
settings?.setExtraParameterForKey("liveramp.com", value: "<liverampEnvelope>")

For more information, see AppLovin's MAX SDK documentation on how to pass identifier tokens for iOS or Android.

Updated 3 months ago