Super Auction Setup for MoPub

To use Super Auction with MoPub as your primary SDK, you’ll need to:

1. Add your Site ID to your app

Ensure your app’s Site ID - found in the SSP UI - is hardcoded in your Verizon Ads SDK integration in as outlined in the “Initializing the SDK” section of the Integration Guide.

2. Integrate the MoPub Super Auction API

In order to manage the display of winning bids, our MoPub upstream adapter exposes a requestBid API that handles the caching and displaying of winning Super Auction bids. MoPub publishers that wish to use Super Auction must integrate the MoPub adapters’ requestBid API for their placements. Please note that this integration is specifically required for MoPub publishers and is different than the generic Super Auction integration detailed in the Super Auction overview.

Requesting a bid for inline placements

// example dimensions
int width = 320, height = 50;
adSize = new AdSize(width, height);
List<AdSize> adSizes = new ArrayList<>();
adSizes.add(adSize);
// Optionally use request metadata builder here to add targeting data

VerizonBanner.requestBid(this, myPlacementId, adSizes, null, this);

@Override
public void onComplete(Bid bid, ErrorInfo errorInfo) {

    if (errorInfo != null) {
        // Error handling here
    } else {
        // Bid object returned for evaluation
        this.bid = bid;
    }
 }
[MPVerizonBannerCustomEvent requestBidForPlacementId:myPlacementId
                                             adSizes:@[self.size]
                                              vasAds:[VASAds sharedInstance]
                                          completion:^(VASBid * _Nullable bid, VASErrorInfo * _Nullable error) {
                                            if (error) {
                                              // Error handling here
                                            } else {
                                              self.bid = bid
                                            }
                                          }];

Requesting a bid for interstitial placements

VerizonInterstitial.requestBid(myActivity, myPlacementId, null, new BidRequestListener() {

@Override
public void onComplete(Bid bid, ErrorInfo errorInfo) {

    if (errorInfo != null) {
        // Error handling here
    } else {
        // Bid object returned for evaluation
        this.bid = bid;
    }
 }
[MPVerizonInterstitialCustomEvent requestBidForPlacementId:myPlacementId
                                                    vasAds:[VASAds sharedInstance]
                                                completion:^(VASBid * _Nullable bid, VASErrorInfo * _Nullable error) {
                                                  if (error) {
                                                    // Error handling here
                                                  } else {
                                                    self.bid = bid
                                                  }
                                                }];

Handling the bid

If there is demand for your bid request, Super Auction will return a Bid object that contains a bid price and an ad that the SDK caches. You then must use the MoPub SDK’s keyword API to pass the bid price to MoPub for evaluation.

Note that only a single bid is stored in cache per placement ID. In other words, if you call the API multiple times, only the last bid returned is available to be used.

2. Create your order in the MoPub console

MoPub_1

3. Setup line items in the MoPub console

Setup line items in the MoPub ad server that correspond with the value of the incoming Super Auction demand. This is done via keyword targeting.

  • After receiving the bid price via Super Auction’s requestBid API, pass this bid price as a keyword parameter to MoPub. You will need to target this bid price with a line item that is set at the same amount as the bid price.
  • If you had 1 line item for every bid at penny increments (i.e. $0.01, $0.02, $0.03, etc.), you’d need 1,000 line items just to account for bids from $1 to $10. That level of granularity would give the most accurate representation of the bids, but it is unwieldy.
  • Instead, publishers typically use price buckets in varying granularity for the price ranges that matter. For example, interstitial ad placements may earn you $4.50 eCPM on average. You could group bids in 10 cent increments from $3-$4 so that bids of $3.04 or $3.06 would be rounded down into a single price bucket of $3.00. Then you could use 5 cent increments for the more important $4-$5 range for increased accuracy. In that case, a $4.04 bid would be rounded down to the $4.00 price bucket, and a $4.06 bid would be rounded down to the $4.05 price bucket.

For each price bucket, create an order with a new line item in the MoPub ad server and follow the instructions below:

Set the line item to Network and give it Priority 12 (MoPub’s default priority level) so that it competes with the rest of your demand. Please note that if you use another priority level as your default, you should use that for this line item. The Network type needs to be set at “Custom Native Network”. The Class and Data that you will enter depends on the OS and placement type. Please reference the table below and replace the JSON data placeholders with the correct values for your placement.

Android

Type Custom Event Class Custom Event Data
Banner com.mopub.mobileads.VerizonBanner {“placementId”:”<placement ID>”, “siteId””:”<site ID>”, “width”:<width here>, “height”:<height here>}
Interstitial com.mopub.mobileads.VerizonInterstitial {“placementId”:”<placement ID>”, “siteId””:”<site ID>”}

iOS

Type Custom Event Class Custom Event Data
Banner MPVerizonBannerCustomEvent {“placementId”:”<placement_ID>”, “siteId””:”<site ID>”, “width”:<width here>,”height”:<height here>}
Interstitial MPVerizonInterstitialCustomEvent {“placementId”:”<placement ID>”, “siteId”:”<site ID>”}

MoPub_2

Next, set your line item to start immediately. The eCPM should be set at the floor of the price bucket. In this example, it is set to $1.00. This line item will compete with your other demand on MoPub (as well as the MoPub Marketplace) at $1.00 eCPM.

Publishers will typically set the eCPM for their line items at the floor of the price bucket, which means bid prices may be higher than the eCPM, especially for less granular setups. There may be other methodologies that work better for you (e.g. setting eCPM as an average price).

MoPub_3

Next, target the MoPub ad unit that corresponds to your Super Auction placement. Note that, because of the line item’s placement and OS-specific Class and Data, each Super Auction placement must have its own MoPub ad unit and set of line items.

MoPub_4

Finally, set your keyword targeting to include all prices within the line item’s price bucket. Note that the keyword can be anything you choose; just make sure it’s the same one you are using to send the Super Auction bid to MoPub. In this example, the keyword is ‘sa_keyword’ and the $1.00 line item includes bids from $1.00 to $1.49.

MoPub_5

4. Add client side auto-refresh for inline ads

When using Super Auction with inline placements, replace MoPub’s server-side auto-refresh with your own client-side implementation.

This is required to maximize your ad revenue by ensuring that each new ad results from the Super Auction bidding process. Move the ad loading code into a separate method and set up a timer that periodically (e.g. every 30 seconds) calls that method to load a new ad. The ad loading method should request a new bid and load a new ad from MoPub using the bid.

Remember to disable MoPub’s built-in refresh timer on the MoPub website