Understand Advanced Bidding

Advanced Bidding is the complete re-imagination of header bidding for the mobile app environment. It’s designed to level the playing field while increasing inventory access and auction efficiency for all ad sources by replacing the traditional ad waterfall with simultaneous real-time bidding (RTB) from ad networks and DSPs.

If you are interested in participating with MoPub as an Advanced Bidding Network:

  1. Visit the Advanced Bidding page on the MoPub website. Its overview video is a good place to start understanding the concepts.
  2. Understand the Advanced Bidding request and response flow.
  3. Understand the Advanced Bidding integration components.
  4. Reach out to our mediation team if you are interested in becoming an Advanced Bidder. In your email, include any relevant information, such as your top geos, formats, and your timeline to start bidding.

Advanced Bidding Request and Response Flow

The Advanced Bidding Overview diagram shows the big picture with all the participants.

Figure 1. Advanced Bidding Overview Advanced Bidding Overview

  1. The publisher app requests an ad from the MoPub SDK.
  2. The MoPub SDK requests bid tokens from the network SDKs via the network adapters.
  3. Network SDKs submit tokens back to the MoPub SDK.
  4. The MoPub SDK requests an ad from the MoPub ad server.
  5. The MoPub ad server requests bids from the MoPub Exchange.
  6. The MoPub Exchange requests bids from two types of third parties, passing the relevant tokens:
    • Advanced Bidding networks (passing the relevant tokens)
    • DSPs
  7. Advanced Bidding networks and other demand sources respond with bids.
  8. The MoPub Exchange collects all received bids and returns them to the MoPub ad server.
  9. The MoPub ad server resolves the auction between eligible bidders and non-bidding demand sources (according to the publisher’s waterfall).
  10. The MoPub ad server responds to the MoPub SDK with the winning ad source.
  11. The publisher app displays the ad. Depending on the winning demand source, the MoPub SDK either
    • Displays the creative, or
    • Passes control to the network SDK for playback

Client-Side Ad Request

Advanced Bidding is triggered when the publisher makes an ad request to the MoPub SDK. Typically, network SDKs have already been initialized at this point.

Figure 2. Publisher Makes an Ad Request to the MoPub SDK

Publisher Ad Request to MoPub SDK

The MoPub SDK then asks all Advanced Bidding network SDKs for a token. Providing a token is optional. If provided, the token is included in the bid request to the network’s bidder, so that the network can use it to communicate between the SDK and the bidder.

Figure 3. The MoPub SDK Asks Advanced Bidding Network SDKs for a Token MoPub SDK Asks AB Network SDKs for Token

The token should be encoded or encrypted so that it is not readable by MoPub.

Finally, the MoPub SDK makes an ad request to the MoPub server, and includes any tokens it has collected.

Figure 4. The MoPub SDK Makes an Ad Request to the MoPub Server, Including Tokens

MoPub SDK Makes Ad Request to Ad Server

Server-Side Bid Request

The MoPub Exchange makes a bid request to all eligible network bidders, in accordance with the MoPub Advanced Bidding Specification.

Figure 5. The MoPub Exchange Makes a Bid Request to Eligible Network Bidders and DSPs

MoPub Exchange Makes Bid Request to Network Bidders

Refer to the sample bid requests.

Server-Side Bid Response

Network bidders respond with a bid to the MoPub Exchange. Bid responses must follow the MoPub Advanced Bidding Specification, which is similar to the OpenRTB 2.3 Specification.

Figure 6. Bidders Respond with a Bid

Bidders Respond with Bid

In OpenRTB, the adm field is typically used for passing the ad markup (creative content), but has increased flexibility for Advanced Bidding. MoPub uses the adm field to pass content from the winning bidder back down to the winning network’s SDK. This content can be any data that the winning network bidder wishes to relay to the network’s SDK. The content is often metadata referencing the creative to fetch, but use of this field is not required at all.

Refer to this sample bid response.

Client-Side Ad Response and Ad Rendering

The MoPub SDK instructs the winning ad source to load an ad. If this winning ad source was an Advanced Bidding network, then the contents of the adm field are passed to the network SDK through the adapters.

Figure 7. The MoPub SDK Instructs the Winning Ad Source to Load an Ad

MoPub SDK Instructs Winner to Load Ad

Depending on the ad format, the publisher app may now instruct the MoPub SDK to show an ad. The step only applies to interstitial and rewarded video formats. MoPub’s banner and native ads currently have no ‘show’ method, and for them, the rendering of the ad should immediately follow a successful ad load without the intermediate ‘show’ step.

Figure 8. The Publisher App Instructs the MoPub SDK to Show Ad

Publisher App Instructs MoPub to Show Ad

This step has no requirements specific to Advanced Bidding. It is identical to any standard mediation interface between MoPub and a supported network.

Lastly, and again depending on the ad format, MoPub may instruct the winning demand source to show the ad. This step, too, applies only to interstitial and rewarded video formats because MoPub’s banner and native ads currently have no ‘show’ method. Here again, there are no requirements specific to Advanced Bidding.

Figure 9. The MoPub SDK Instructs the Winning Demand Source to Show Ad

MoPub Tells Winner to Show Ad

Advanced Bidding Integration Components

The Advanced Bidding integration consists of 3 required components:

Component Owner Resources Notes
Network Bidder Network MoPub Advanced Bidding Spec
Sample bid requests & responses
The MoPub team recommends reviewing the sample bid requests & responses first, and leveraging the complete spec for any questions on specific fields.
SDK Adapter MoPub The MoPub team will direct you to sample code The MoPub Solutions Engineering team will work with you to make the necessary updates to the adapters to support Advanced Bidding. The network will resume maintenance of each version from that point forward.
Validation Reporting Network Sample daily report
Sample monthly report
MoPub will leverage these daily and monthly reports for troubleshooting and billing validation purposes.

Sample Bid Requests and Responses

Sample Interstitial Bid Request

{
  "app": {
    "bundle": "com.mopub.simpleadsdemo", 
    "cat": [
      "IAB1", 
      "IAB1-1", 
      "books"
    ], 
    "id": "f1e98e7a55ca489aadce956148266065", 
    "name": "MoPub Sample App", 
    "publisher": {
      "id": "1308c11342c349e8a2934d8bb8fd33f6", 
      "name": "Twitter"
    }, 
    "ver": "4.20.0"
  }, 
  "at": 1, 
  "bcat": [
    "IAB25", 
    "IAB26", 
    "IAB7-39", 
    "IAB8-18", 
    "IAB8-5", 
    "IAB9-9", 
    "IAB3-7"
  ], 
  "device": {
    "connectiontype": 2, 
    "dnt": 0, 
    "geo": {
      "city": "New York", 
      "country": "USA", 
      "lat": 40.7417, 
      "lon": -73.9997, 
      "metro": "501", 
      "region": "NY", 
      "zip": "10011"
    }, 
    "h": 1280, 
    "ifa": "3c0fcf11-a446-4172-9e68-2db6e07db720", 
    "ip": "192.133.79.145", 
    "js": 1, 
    "language": "en", 
    "make": "samsung", 
    "model": "SM-J700H", 
    "os": "Android", 
    "osv": "5.0.0", 
    "pxratio": 2.0, 
    "ua": "Mozilla/5.0 (Linux; Android 5.0; SM-G900P Build/LRX21T) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.139 Mobile Safari/537.36", 
    "w": 720
  }, 
  "ext": {
    "pchain": "74b46c0ea83967ca:1308c11342c349e8a2934d8bb8fd33f6"
  }, 
  "id": "70e21e6d-a8b3-43cb-9562-b5bc59995038", 
  "imp": [
    {
      "banner": {
        "api": [
          3, 
          5
        ], 
        "battr": [
          3, 
          8, 
          9, 
          10, 
          14
        ], 
        "btype": [
          4
        ], 
        "h": 480, 
        "pos": 1, 
        "w": 320
      }, 
      "bidfloor": 0.01, 
      "displaymanager": "mopub", 
      "displaymanagerver": "5.0.0", 
      "ext": {
        "brsrclk": 1, 
        "dlp": 1, 
        "metric": [
          {
            "type": "viewability", 
            "vendor": "ias"
          }, 
          {
            "type": "viewability", 
            "vendor": "moat"
          }
        ], 
        "networkids": {
          "appid": "NETWORK_APP_ID", 
          "placementid": "NETWORK_PLACEMENT_ID"
        }
      }, 
      "id": "1", 
      "instl": 1, 
      "secure": 0, 
      "tagid": "8a72ab6e7f47466caf5c720ca7b975e7", 
      "video": {
        "api": [
          3, 
          5
        ], 
        "battr": [
          3, 
          8, 
          9, 
          10, 
          14
        ], 
        "companiontype": [
          1, 
          2, 
          3
        ], 
        "h": 480, 
        "linearity": 1, 
        "maxduration": 120, 
        "mimes": [
          "video/mp4", 
          "video/3gpp"
        ], 
        "minduration": 0, 
        "protocols": [
          2, 
          5, 
          3, 
          6
        ], 
        "w": 320
      }
    }
  ], 
  "user": {
    "buyeruid": "NETWORK_TOKEN"
  }
}

Sample Banner Bid Request

{
  "app": {
    "bundle": "com.mopub.simpleadsdemo", 
    "cat": [
      "IAB1", 
      "IAB1-1", 
      "books"
    ], 
    "id": "f1e98e7a55ca489aadce956148266065", 
    "name": "Advanced Bidding Test App (iOS)", 
    "publisher": {
      "id": "1308c11342c349e8a2934d8bb8fd33f6", 
      "name": "Twitter"
    }, 
    "ver": "4.20.0"
  }, 
  "at": 2, 
  "bcat": [
    "IAB25", 
    "IAB26", 
    "IAB7-39", 
    "IAB8-18", 
    "IAB8-5", 
    "IAB9-9", 
    "IAB3-7"
  ], 
  "device": {
    "connectiontype": 2, 
    "dnt": 0, 
    "geo": {
      "country": "USA", 
      "lat": 40.7416, 
      "lon": -73.9998, 
      "region": "NY"
    }, 
    "h": 1280, 
    "ip": "8.25.196.26", 
    "js": 1, 
    "language": "en", 
    "make": "samsung", 
    "model": "SM-J700H", 
    "os": "Android", 
    "osv": "5.0.0", 
    "pxratio": 2.0, 
    "ua": "Mozilla/5.0 (Linux; Android 5.0; SM-G900P Build/LRX21T) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.139 Mobile Safari/537.36", 
    "w": 720
  }, 
  "ext": {
    "pchain": "74b46c0ea83967ca:1308c11342c349e8a2934d8bb8fd33f6"
  }, 
  "id": "288fa9b5-41df-4f22-8da5-6413afb25735", 
  "imp": [
    {
      "bidfloor": 0.01, 
      "displaymanager": "mopub", 
      "displaymanagerver": "5.0.0", 
      "ext": {
        "brsrclk": 1, 
        "dlp": 1, 
        "metric": [
          {
            "type": "viewability", 
            "vendor": "ias"
          }, 
          {
            "type": "viewability", 
            "vendor": "moat"
          }
        ], 
        "networkids": {
          "appid": "NETWORK_APP_ID", 
          "placementid": "NETWORK_PLACEMENT_ID"
        }
      }, 
      "id": "1", 
      "instl": 1, 
      "secure": 0, 
      "tagid": "aef0b2c756594f38856539f8316c4dca", 
      "video": {
        "battr": [
          3, 
          8, 
          9, 
          10, 
          14, 
          7
        ], 
        "companiontype": [
          1, 
          2, 
          3
        ], 
        "ext": {
          "skip": 0, 
          "videotype": "rewarded"
        }, 
        "h": 320, 
        "linearity": 1, 
        "maxduration": 30, 
        "mimes": [
          "video/mp4", 
          "video/3gpp"
        ], 
        "minduration": 0, 
        "protocols": [
          2, 
          5, 
          3, 
          6
        ], 
        "w": 480
      }
    }
  ], 
  "user": {
    "buyeruid": "NETWORK_TOKEN"
  }
}

Sample Native Bid Request

{
  "app": {
    "bundle": "com.mopub.Canary", 
    "cat": [
      "IAB1", 
      "IAB1-1", 
      "books"
    ], 
    "id": "d9b055d66a2e4230b8aaeb00b268c8cf", 
    "name": "Advanced Bidding (iOS)", 
    "publisher": {
      "id": "506317839546454", 
      "name": "Twitter"
    }, 
    "storeurl": "http://www.com.com", 
    "ver": "1.0"
  }, 
  "at": 2, 
  "bcat": [
    "IAB3-7"
  ], 
  "device": {
    "carrier": "311-480", 
    "connectiontype": 2, 
    "devicetype": 4, 
    "dnt": 0, 
    "geo": {
      "city": "New York", 
      "country": "USA", 
      "metro": "501", 
      "region": "NY", 
      "zip": "10118"
    }, 
    "h": 2001, 
    "hwv": "iPhone7,1", 
    "ifa": "744CD401-77B4-40AA-AF80-ADDE40B1D747", 
    "ip": "8.25.196.25", 
    "js": 1, 
    "language": "en", 
    "make": "Apple", 
    "model": "iPhone", 
    "os": "iOS", 
    "osv": "11.0", 
    "pxratio": 3.0, 
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604.1", 
    "w": 1125
  }, 
  "ext": {
    "pchain": "74b46c0ea83967ca:1308c11342c349e8a2934d8bb8fd33f6", 
    "platformid": "545275759148286"
  }, 
  "id": "36f5bb90-2355-4399-bc2b-df72e65f495b", 
  "imp": [
    {
      "bidfloor": 0.01, 
      "displaymanager": "mopub", 
      "displaymanagerver": "5.0.0", 
      "ext": {
        "brsrclk": 1, 
        "dlp": 1, 
        "networkids": {
          "appid": "NETWORK_APP_ID", 
          "placementid": "NETWORK_PLACEMENT_ID"
        }
      }, 
      "id": "1", 
      "instl": 0, 
      "native": {
        "h": -1, 
        "request": "{\"native\":{\"assets\":[{\"data\":{\"len\":15,\"type\":12},\"id\":5,\"required\":0},{\"id\":3,\"img\":{\"hmin\":80,\"type\":1,\"wmin\":80},\"required\":1},{\"id\":2,\"img\":{\"h\":627,\"hmin\":417,\"type\":3,\"w\":1200,\"wmin\":800},\"required\":1},{\"data\":{\"type\":3},\"id\":6,\"required\":0},{\"data\":{\"len\":150,\"type\":2},\"id\":4,\"required\":1},{\"id\":1,\"required\":1,\"title\":{\"len\":50}}]}}", 
        "ver": "1.0.0.2", 
        "w": -1
      }, 
      "secure": 1, 
      "tagid": "506317839546454_844799319031636"
    }
  ], 
  "regs": {
    "ext": {
      "gdpr": 0
    }
  }, 
  "test": 1, 
  "tmax": 300, 
  "user": {
    "buyeruid": "NETWORK_TOKEN"
  }
}

Sample Rewarded Video Bid Request

{
  "app": {
    "bundle": "com.mopub.simpleadsdemo", 
    "cat": [
      "IAB1", 
      "IAB1-1", 
      "books"
    ], 
    "id": "f1e98e7a55ca489aadce956148266065", 
    "name": "Advanced Bidding AdColony - Android", 
    "publisher": {
      "id": "1308c11342c349e8a2934d8bb8fd33f6", 
      "name": "Twitter"
    }, 
    "ver": "4.20.0"
  }, 
  "at": 1, 
  "bcat": [
    "IAB25", 
    "IAB26", 
    "IAB7-39", 
    "IAB8-18", 
    "IAB8-5", 
    "IAB9-9", 
    "IAB3-7"
  ], 
  "device": {
    "connectiontype": 2, 
    "dnt": 0, 
    "geo": {
      "country": "USA", 
      "lat": 40.7416, 
      "lon": -73.9998, 
      "region": "NY"
    }, 
    "h": 1280, 
    "ip": "8.25.196.26", 
    "js": 1, 
    "language": "en", 
    "make": "samsung", 
    "model": "SM-J700H", 
    "os": "Android", 
    "osv": "5.0.0", 
    "pxratio": 2.0, 
    "ua": "Mozilla/5.0 (Linux; Android 5.0; SM-G900P Build/LRX21T) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.139 Mobile Safari/537.36", 
    "w": 720
  }, 
  "ext": {
    "pchain": "74b46c0ea83967ca:1308c11342c349e8a2934d8bb8fd33f6"
  }, 
  "id": "288fa9b5-41df-4f22-8da5-6413afb25735", 
  "imp": [
    {
      "bidfloor": 0.01, 
      "displaymanager": "mopub", 
      "displaymanagerver": "5.0.0", 
      "ext": {
        "brsrclk": 1, 
        "dlp": 1, 
        "metric": [
          {
            "type": "viewability", 
            "vendor": "ias"
          }, 
          {
            "type": "viewability", 
            "vendor": "moat"
          }
        ], 
        "networkids": {
          "appid": "NETWORK_APP_ID", 
          "placementid": "NETWORK_PLACEMENT_ID"
        }
      }, 
      "id": "1", 
      "instl": 1, 
      "secure": 0, 
      "tagid": "aef0b2c756594f38856539f8316c4dca", 
      "video": {
        "battr": [
          3, 
          8, 
          9, 
          10, 
          14, 
          7
        ], 
        "companiontype": [
          1, 
          2, 
          3
        ], 
        "ext": {
          "skip": 0, 
          "videotype": "rewarded"
        }, 
        "h": 320, 
        "linearity": 1, 
        "maxduration": 30, 
        "mimes": [
          "video/mp4", 
          "video/3gpp"
        ], 
        "minduration": 0, 
        "protocols": [
          2, 
          5, 
          3, 
          6
        ], 
        "w": 480
      }
    }
  ], 
  "user": {
    "buyeruid": "NETWORK_TOKEN"
  }
}

Sample Bid Response

{
  "bidid": "c39896564ab4570915", 
  "cur": "USD", 
  "id": "70e21e6d-a8b3-43cb-9562-b5bc59995038", 
  "seatbid": [
    {
      "bid": [
        {
          "adm": "ADVANCED_BIDDER", 
          "id": "test_bid", 
          "impid": "1", 
          "iurl": "", 
          "nurl": "https://www.advancedbidder.com/network/nurl/?partner=256699801203835&app=256699801203835&placement=326140227593125&auction=banner_test_bid_req_id&impression=banner_test_bid_req_imp_id&request=8297257243807848103&bid=4286570256979209201&ortb_loss_code=0", 
          "price": 99.0, 
        }
      ], 
    }
  ]
}

Sample Native Bid Response

{
   "bidid": "7546804272925719591",
   "cur": "USD"
   "id": "36f5bb90-2355-4399-bc2b-df72e65f495b",
   "seatbid": [
      {
         "bid": [
            {
               "id": "2888075278428220704",
               "impid": "1",
               "adm": "{\"type\":\"ID\",\"bid_id\":\"2888075278428220704\",\"placement_id\":\"506317839546454_844799319031636\",\"resolved_placement_id\":\"506317839546454_844799319031636\",\"sdk_version\":\"4.28.1\",\"device_id\":\"744CD401-77B4-40AA-AF80-ADDE40B1D747\",\"template\":200,\"payload\":null,\"bidtimetoken\":\"V1_eyJwbGF0Zm9ybV9pZCI6NTQ1Mjc1NzU5MTQ4Mjg2fQ==\"}",
               "nurl": "https://www.advancedbidder.com/network/nurl/?partner=256699801203835&app=256699801203835&placement=326140227593125&auction=banner_test_bid_req_id&impression=banner_test_bid_req_imp_id&request=8297257243807848103&bid=4286570256979209201&ortb_loss_code=0", 
               "price": 99.99,
            }
         ]
      }
   ],
}

Sample Validation Reports

Sample Daily Validation Report

date app_ID pub_name app_name OS ad_format bid_requests_received valid_bids_returned impressions wins pub_cpm spend
2019-03-01 818754181479601 Pub name text Uncrossed iOS Interstitial 284673 207249 41043 36017 3.02233 376.7435077
2019-03-01 181360805703034 Pub name text 胴上げ祭り iOS Interstitial 35502 13360 587 73467 42.42857 7.792958566
2019-03-01 818754181479601 Pub name text Test App iOS Banner 2580278 1828115 211704 34563456 3.02233 64.88535385
2019-03-01 1630733693809559 Pub name text FocusedMan Android Interstitial 248579 189135 35783 345 42.42857 71.26034276
2019-03-01 10152593451449604 Pub name text MLB Tap Sports Baseball 2019 iOS Rewarded Video 104451 78749 17311 8678 4.98709 119.3469861
2019-03-01 818754181479601 Pub name text Uncrossed Android Rewarded Video 83905 67491 40727 45322 4.62086 310.035646
2019-03-01 10152593451449604 Pub name text CookOff Android Native 0 0 0 225546 2.94031 71.26034276
2019-03-01 818754181479601 Pub name text Uncrossed Android Native 0 0 0 6345 3.02233 0

Sample Monthly Validation Report

app_ID pub_name app_name OS ad_format bid_requests_received valid_bids_returned wins impressions pub_cpm spend
862258100463574 Pub name text 4 Pics 1 Word iOS Interstitial 4139178 3122202 36017 71751 3.02233 173.63375
818754181479601 Pub name text Wordscapes Uncrossed Android Native 4139178 3122202 73467 0 42.42857 34.12000
10152129083228034 Pub name text FreeCell   Banner 4139178 3122202 52837 166 3.02233 0.00005
10152593451449604 Pub name text Design Home Android Native 4139178 3122202 35720 0 42.42857 0.00079
899156253477457 Pub name text AN Video - Metro UK iOS Native 4139178 3122202 77037   4.98709  
1150448308370833 Pub name text Golf Orbit Android Native 4139178 3122202 52787 0 4.62086 0.00138
1150448308370833 Pub name text Terrarium   Rewarded Video 4139178 3122202 44780 12 2.94031 0.00000
1178573945502671 Pub name text PicsArt Photo Studio iOS Native 4139178 3122202 77037   3.02233  
1150448308370833 Pub name text Emoji Craft ! Android Rewarded Video 4139178 3122202 77037 0 42.42857 0.00000

Last updated October 06, 2020

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2020 MoPub (a division of Twitter, Inc.)