Buyer SDK ad format

Buyer SDK ads use creatives rendered by your own SDK.

Mobile app inventory from publishers who integrate your bidding adapter into their app can accept bids with the buyer SDK rendered ad format. How they render is based on your SDK implementation and the SDKRenderedAd you submit in the bid response.

You can place a bid including either a buyer SDK rendered ad or any other ad format supported by the Google Mobile Ads SDK, but any bids containing both are filtered.

Requirements

Buyer SDK ads are available to approved buyers. This format requires extra effort from you and the publisher. Contact your Technical Account Manager to configure your account for buyer SDK ads. You can then implement a Bidding adapter that enables your SDK to communicate with the Google Mobile Ads SDK. The publisher needs to integrate your SDK and adapter into their mobile apps.

We recommend you submit creatives for review before including them in a bid response. Contact your Technical Account Manager if you don't know the creative type at bid time.

If a bid request supports this ad format, you can specify an ad that renders with your SDK by setting the sdk_rendered_ad field in the bid response.

Bid request

Bid requests for mobile app inventory include details about the SDKs and adapters in the publisher's app that you can use for rendering in the following fields:

SDK ID

You can use the bid request to find the id that you must provide in the bid response for a buyer SDK rendered ad.

See the following fields:

• OpenRTB: BidRequest.app.ext.installed_sdk
• Google RTB protocol (deprecated): BidRequest.mobile.installed_sdk

You can learn more about the InstalledSdk message in the OpenRTB and Google protocol guides.

Ad Unit Mapping

You can use the bid request to read ad unit mappings that match the bid slot.

See the following fields:

• OpenRTB: BidRequest.imp.ext.ad_unit_mapping
• Google RTB protocol (deprecated): BidRequest.AdSlot.ad_unit_mapping

You can learn more about the AdUnitMapping object in the OpenRTB and Google protocol guides.

Secure Signals

Publishers can share secure signals with bidders. You can read them from OpenRTB's BuyerGeneratedRequestData object or from the deprecated Google RTB protocol's SecureSignal object.

See the following fields:

• OpenRTB: BidRequest.imp.ext.buyer_generated_request_data.data
• Google RTB protocol (deprecated): BidRequest.AdSlot.SecureSignal.data

You can learn more about how secure signals are represented in the OpenRTB and Google protocol guides.

Test Requests

You can read the Test Request field to understand if the bid request is a test.

See the following fields:

• OpenRTB: BidRequest.test
• Google RTB protocol (deprecated): BidRequest.is_test

You can learn more about the Test field in the OpenRTB and Google protocol guides.

Sample bid request

id: "<bid_request_id>"
imp {
  id: "1"
  banner {
    w: 320
    h: 50
    ...
  }
...
  adx_ext {
   ...
    ad_unit_mapping {
      keyvals {
        key: "key_1"
        value: "value_1"
      }
      keyvals {
        key: "key_2"
        value: "value_2"
      }
      ...
      format: FORMAT_BANNER
    }
  }
}
app {
 ...
  adx_ext {
    installed_sdk {
      id: "com.google.ads.mediation.partner.PartnerMediationAdapter"
      sdk_version {
        major: 1
        minor: 2
        micro: 30
      }
      adapter_version {
        major: 1
        minor: 2
        micro: 3000
      }
    }
    installed_sdk {
    ...
    }
    ...
  }
}
device {
  ...
}
user {
  ...
  }
  adx_ext {
    eids {
      source: "com.google.ads.mediation.partner.PartnerMediationAdapter"
      uids {
        id: "<partner_signal_string>"
      }
    }
  }
}
at: 1
tmax: 1000
cur: "USD"
test: 1
...
adx_ext {
  google_query_id: "<query_string>"
  ...
}

Bid response

Important: Buyers should always refer to this document to determine which fields are required for SDK Bidding. Some fields required for SDK Bidding might be marked as optional in the OpenRTB integration guide.

The following fields are required in the bid response:

• OpenRTB:
  • BidResponse.seatbid.bid.adomain
  • BidResponse.seatbid.bid.ext.billing_id
  • BidResponse.seatbid.bid.crid
  • BidResponse.seatbid.bid.w
  • BidResponse.seatbid.bid.h
• Google RTB protocol (deprecated):
  • BidResponse.Ad.click_through_url
  • BidResponse.Ad.AdSlot.billing_id
  • BidResponse.Ad.buyer_creative_id
  • BidResponse.Ad.width
  • BidResponse.Ad.height

Additionally, your bid response must include an SdkRenderedAd with the following:

SDK ID

Use the id field to provide the ID for the SDK to render the ad.

You can find the ID in the bid request with the following fields:

• OpenRTB: BidRequest.app.ext.installed_sdk
• Google RTB protocol (deprecated): BidRequest.mobile.installed_sdk

You can learn more about the InstalledSdk message in the OpenRTB and Google protocol guides.

Declared ad

Use a declared_ad field to provide a creative that meets the bid request's CreativeEnforcementSettings requirements and is representative of the ad's rendering data. Only one of html_snippet, video_url, video_vast_xml, or native_response should be populated.

• OpenRTB: BidResponse.seatbid.bid.ext.sdk_rendered_ad.declared_ad
• Google RTB protocol (deprecated): BidResponse.ad.sdk_rendered_ad.declared_ad

If you don't populate declared_ad, we're unable to review the creative and all bids with the creative are filtered from the auction.

Rendering data

Use the rendering_data field to provide the data for the buyer SDK to use to render your ad.

• OpenRTB: BidResponse.seatbid.bid.ext.sdk_rendered_ad.rendering_data
• Google RTB protocol (deprecated): BidResponse.ad.sdk_rendered_ad.rendering_data

Bids to place a buyer SDK ad must specify a creative in the declared_ad field. The declared ad must accurately represent the rendering_data.

Here's a sample SdkRenderedAd object:

{
  "id": "1234567",
  "rendering_data": "\xd58...,\xd4\x89\xd\xf9",
  "declared_ad": {
    "html_snippet": "<iframe src=\"https://example.com/ads?id=123&
      curl=%%CLICK_URL_ESC%%&wprice=%%WINNING_PRICE_ESC%%\"></iframe>",
  }
}

We recommend using the Real-time Bidding API to submit creatives for review before you include them in a bid response.

See the Google and OpenRTB protocol guides for more details on the SdkRenderedAd fields.

Sample bid response

Here are sample bid responses for each ad format:

Banner

id: "<bid_request_id>"
seatbid {
  bid {
    id: "<bidder_generated_response_id>"
    impid: "1"
    price: 99
    adomain: "https://play.google.com/store/apps/details?id=com.test.app"
    cid: "<billing_id>"
    crid: "<creative_id>"
    w: 320
    h: 50
    burl: "https://abc.com/billing?td=fn&win_price=${AUCTION_PRICE}"
    adx_ext {
      sdk_rendered_ad {
        id: "com.google.ads.mediation.partner.PartnerMediationAdapter"
        rendering_data: "<rendering_data_string>"
        declared_ad {
          click_through_url: "https://play.google.com/store/apps/details?id=com.test.app"
          html_snippet: "<!doctype html> <html> ... </html>"
        }
      }
      event_notification_token {
        payload: "<payload_string>"
      }
      billing_id: 141763360450
    }
  }
}
bidid: "<bidder_generated_response_id>"
cur: "USD"

Interstitial

id: "<bid_request_id>"
seatbid {
  bid {
    id: "<bidder_generated_response_id>"
    impid: "1"
    price: 400
    adomain: "https://play.google.com/store/apps/details?id=com.test.app"
    cid: "<billing_id>"
    crid: "<creative_id>"
    w: 412
    h: 775
    adx_ext {
      sdk_rendered_ad {
        id: "com.google.ads.mediation.partner.PartnerMediationAdapter"
        rendering_data: "<rendering_data_string>"
        declared_ad {
          click_through_url: "https://play.google.com/store/apps/details?id=com.test.app"
          video_vast_xml: "<VAST version=\"2.0\"><Ad>...</Ad></VAST>"
        }
      }
      event_notification_token {
        payload: "<payload_string>"
      }
    }
  }
}
bidid: "<bidder_generated_response_id>"
cur: "USD"

Rewarded video

id: "<bid_request_id>"
seatbid {
  bid {
    id: "<bidder_generated_response_id>"
    impid: "1"
    price: 400
    adomain: "https://play.google.com/store/apps/details?id=com.test.app"
    cid: "<billing_id>"
    crid: "<creative_id>"
    w: 412
    h: 775
    adx_ext {
      sdk_rendered_ad {
        id: "com.google.ads.mediation.partner.PartnerMediationAdapter"
        rendering_data: "<rendering_data_string>"
        declared_ad {
          click_through_url: "https://play.google.com/store/apps/details?id=com.test.app"
          video_vast_xml: "<VAST version=\"2.0\"><Ad>...</Ad></VAST>"
        }
      }
      event_notification_token {
        payload: "<payload_string>"
      }
    }
  }
}
bidid: "<bidder_generated_response_id>"
cur: "USD"

Native

id: "<bid_request_id>"
seatbid {
  bid {
    id: "<bidder_generated_response_id>"
    impid: "1"
    price: 400
    adomain: "https://play.google.com/store/apps/details?id=com.test.app"
    cid: "<billing_id>"
    crid: "<creative_id>"
    w: 1200
    h: 627
    adx_ext {
      sdk_rendered_ad {
        id: "com.google.ads.mediation.partner.PartnerMediationAdapter"
        rendering_data: "<rendering_data_string>"
        declared_ad {
          click_through_url: "https://play.google.com/store/apps/details?id=com.test.app"
          native_response {
            ...
            assets {
              id: 1
              title {
                text: ""
              }
            }
            assets {
              id: 2
              data {
                value: "<some_string>"
              }
            }
            assets {
              id: 3
              data {
                value: "View now"
              }
            }
            assets {
              id: 4
              img {
                url: "<valid_image_url>"
                w: 1200
                h: 627
                type: 3
              }
            }
            assets {
              id: 5
              img {
                url: "<valid_image_url>"
                w: 100
                h: 100
                type: 1
              }
            }
            assets {
              id: 6
              data {
                value: ""
              }
            }
            assets {
              id: 7
              data {
                value: "<some_string>"
              }
            }
            link {
              url: "<destination_link>"
            }
          }
        }
      }
      event_notification_token {
        payload: "<payload_string>"
      }
    }
  }
}
bidid: "<bidder_generated_response_id>"
cur: "USD"

Creative review

Creatives are reviewed before they can serve to ensure they meet our policies and publisher settings.

Warning: Creatives that aren't reviewed are filtered from the auction.

Here are two ways you can submit creatives for review:

Real-time Bidding API (recommended)

You can use the buyers.creatives.create method of the Real-time Bidding API to submit creatives for review.

The API requires only one submission per creative and lets you check the status of your creative's review.

Bid response

You can submit new creatives directly in the bid response.

You must use the declared_ad field of the SdkRenderedAd object to submit a bid response with a buyer SDK creative for review.

Creatives submitted in the bid response are only reviewed after many bids. All bids placed before the review is complete are filtered from the auction. You can use the Real-time Bidding interface or Real-time Bidding API to check the status of a creative after the review starts.

See the creatives guide for more details.