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 SDK ID that you must provide in the bid response with the
BidRequest.app.ext.installed_sdk.id
field.You can learn more about this in the
InstalledSdk
reference documentation.- Ad Unit Mapping
You can use the bid request to find the ad unit mappings that match the bid slot with the
BidRequest.imp.ext.ad_unit_mapping
field.You can learn more about this in the
AdUnitMapping
reference documentation.- Secure Signals
Publishers can share secure signals with bidders. You can find these in
BidRequest.imp.ext.buyer_generated_request_data.data
.You can learn more about how secure signals are represented in the
BuyerGeneratedRequestData
reference documentation.- Test Requests
You can use the
BidRequest.test
field to verify whether the bid request is a test.You can learn more about the this field in the
BidRequest
reference documentation.
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
The following fields are required in the bid response:
BidResponse.seatbid.bid.adomain
BidResponse.seatbid.bid.ext.billing_id
BidResponse.seatbid.bid.crid
BidResponse.seatbid.bid.w
BidResponse.seatbid.bid.h
Additionally, your bid response must populate
BidResponse.seatbid.bid.ext.sdk_rendered_ad
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
BidRequest.app.ext.installed_sdk
.- Declared ad
Use
BidResponse.seatbid.bid.ext.sdk_rendered_ad.declared_ad
to provide a creative that meets the requirements found inBidRequest.imp.ext.creative_enforcement_settings
and is representative of the ad's rendering data. Only one ofhtml_snippet
,video_url
,video_vast_xml
, ornative_response
should be populated.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.You can learn more about the declared ad in the
DeclaredAd
reference documentation.- Rendering data
Use the
BidResponse.seatbid.bid.ext.sdk_rendered_ad.rendering_data
field to provide the data for the buyer SDK to use to render your ad.Bids to place a buyer SDK ad must specify a creative in the
declared_ad
field. The declared ad must accurately represent therendering_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
OpenRTB guide 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.
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 theSdkRenderedAd
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.