LiftoffAds Header Bidding

The LiftoffAds SDK supports header bidding for all ad formats. Contact your Liftoff POC to set up your Liftoff bidding endpoint URL and ad units.

Requirements

Header bidding requires the following minimum SDK versions:

• iOS: 1.7.0
• Android: 1.2.1

We encourage you to update to our latest SDK versions when they become available.

Ad Lifecycle

1. After SDK initialization, retrieve the LiftoffAds SDK bidding token:
   • iOS: Liftoff.biddingToken
   • Android: Liftoff.biddingToken(Context)
2. During your header bidding auction for each ad request, send an OpenRTB 2.5 bid request to your LiftoffAds bidding endpoint URL with the following required fields (see sample bid request below):
   • .id (a unique ID you generate for each bid request, we recommend a UUID)
   • .device.ip (see Device IP below)
   • .imp[].id
   • .imp[].banner.w (see Width and Height below)
   • .imp[].banner.h (see Width and Height below)
   • .imp[].ext.networkids.placementid (your LiftoffAds ad unit ID)
   • .user.buyeruid (the LiftoffAds bidding token)
3. The bid response you receive will either be a 204 response (indicating no bid), or a 200 response with the following OpenRTB bid response fields (see sample bid response below):
   • .id (matches bid request's .id)
   • .seatbid[].bid[].id
   • .seatbid[].bid[].impid (matches bid request's .imp[].id)
   • .seatbid[].bid[].price (CPM, in USD)
   • .seatbid[].bid[].burl
   • .seatbid[].bid[].adm (payload to display ad)
4. If LiftoffAds is the auction winner, send the .seatbid[].bid[].adm value to your app.
5. To display a LiftoffAds ad won via header bidding, instantiate an ad object as normal and pass the adm payload to the ad (see code samples below).
6. All ad callbacks will be fired as normal.

Device IP

If you send header bidding requests from client devices (rather than server-to-server), notify your Liftoff POC. For these requests, .device.ip is not required in the request.

Width and Height

.imp[].banner is required for all requests, including video and native. The values of .w and .h should be equivalent to the width and height, respectively, of the space available for the ad in device-independent pixels. Alternatively, they can be one of the standard ad sizes. IMPORTANT: For native requests, the values of .w and .h should both be 0.

Samples

Bid Request

{
  "id": "be0545d0-fcdd-11ea-86e8-a9516ccbd617_1234242183",
  "device": {
    "ip": "82.81.228.240"
  },
  "imp": [
    {
      "id": "1",
      "banner": {
        "h": 480,
        "w": 320
      },
      "ext": {
        "networkids": {
          "placementid": "LIFTOFF_AD_UNIT_ID"
        }
      }
    }
  ],
  "user": {
    "buyeruid": "yohnDVx6DDT8hBf8ePFR6LU3gdk2kBpKW/nzQkRkO5rsh0CFk+ewTicnnpZKv3hTxOu0/7CytYlxgJZ9H2xyHj6RgfnvSD7CXr3H4pLe5xmaRrjLTkL1HxZIc12XCALIy135rh9iznpAhEsLM24Mka2c4nUvpQWRXehr+1VrbzH48AA/0fi9M2XNtsIaWzGd8vC7JTuAb03jQUDULGmuagQV9jUQpHSITFZcD0nWLk3G6BbGw54UwYKceMRkMXykcw4sWJOja7s+rSt1um8wehF6iA+AUbSmtgN5YnD83X/LU1f0JjUzUWUxwKb7oFGlmxm6+Vfnpw=="
  }
}

Bid Response

{
  "id": "be0545d0-fcdd-11ea-86e8-a9516ccbd617_1234242183",
  "seatbid": [
    {
      "bid": [
        {
          "id": "liftoff-bid-id",
          "impid": "1",
          "price": 1.23,
          "burl": "https://impression.liftoff.io",
          "adm": "0qwObFAwSzP3mBD8ZOlH67Ey1K09hw9IWKaoH0RtLsIK9TnIxbCnG3d408AB4G8DkkeBaM5q4qTmSpA="
        }
      ]
    }
  ]
}

Ad Load (iOS)

See iOS SDK for additional code samples.

// Banner and MRECT
self.loBanner = Liftoff.initBannerAdUnit(for: LIFTOFF_BANNER_AD_UNIT, size: LOConstants.phoneBanner)
self.loBanner.delegate = self
self.loBanner.requestAd(ADM_VALUE)

// Interstitial and rewarded
self.loInterstitial = Liftoff.initInterstitialAdUnit(for: LIFTOFF_INTERSTITIAL_AD_UNIT)
self.loInterstitial.delegate = self
self.loInterstitial.requestAd(ADM_VALUE)

// Native
self.loNative = Liftoff.initNativeAdUnit(for: LIFTOFF_NATIVE_AD_UNIT)
self.loNative.viewAdapter = self.nativeView
self.loNative.delegate = self
self.loNative.requestAd(ADM_VALUE)

Ad Load (Android)

See Android SDK for additional code samples.

// Banner and MRECT
this.loBanner = Liftoff.newBanner(
  activity = this,
  LIFTOFF_BANNER_AD_UNIT,
  AdSize.PHONE_BANNER_FLEX_WIDTH,
  listener = this
)
this.loBanner.load(ADM_VALUE)

// Interstitial and rewarded
this.loInterstitial = Liftoff.newInterstitial(
  activity = this,
  LIFTOFF_INTERSTITIAL_AD_UNIT,
  listener = this
)
this.loInterstitial.load(ADM_VALUE)

// Native
this.loNative = Liftoff.newNative(
  activity = this,
  LIFTOFF_NATIVE_AD_UNIT,
  LONative.ViewBinder(
    layout = R.layout.native_ad,
    parent = nativePlaceholderView,
    title = R.id.nativeAdTitle,
    desc = R.id.nativeAdDescription,
    callToAction = R.id.nativeAdCTA,
    icon = R.id.nativeAdIcon,
    mainImage = R.id.nativeAdMainImage
  ),
  listener = this
)
this.loNative.load(ADM_VALUE)

Troubleshooting

• Ensure that your requests include all of the required fields, in particular the .device.ip field.
• Ensure that you are passing the value of .seatbid[].bid[].adm when calling the requestAd (iOS) or load (Android) methods.