Setelah aplikasi Anda memproses permintaan bid dari Google, aplikasi harus membuat dan mengirim respons. Panduan ini menjelaskan cara membuat kode aplikasi untuk membangun respons.
Membuat pesan BidResponse
Untuk mengajukan bid, aplikasi bidding Anda harus merespons permintaan bid dengan
BidResponse yang berisi Bid dalam format yang Anda
konfigurasi. Jika Anda menggunakan format JSON, respons Anda harus menetapkan header Content-Type ke application/json; charset=utf-8 dan menyertakan BidResponse JSON dalam isi. Jika Anda menggunakan format Protobuf, aplikasi Anda harus menetapkan header Content-Type ke application/octet-stream dan menyertakan BidResponse yang diserialisasi dalam isi.
Untuk mem-build dan melakukan serialisasi BidResponse untuk format Protobuf,
Anda harus membuat dan menggunakan library Protobuf berdasarkan
openrtb.proto dan openrtb-adx.proto, yang
masing-masing mengimplementasikan kolom BidResponse OpenRTB standar dan ekstensi
Google di Protobuf. Ini dapat ditemukan di
Proto & Data Referensi.
Jika tidak ingin mengajukan bid untuk tayangan iklan, Anda harus menampilkan respons HTTP 204 kosong. Aplikasi Anda harus menampilkan respons untuk setiap
BidRequest. Waktu tunggu dan respons yang tidak dapat diuraikan dianggap sebagai error dan Google akan membatasi bidder dengan tingkat error yang tinggi.
ID Materi Iklan
BidResponse Anda menentukan materi iklan melalui kolom BidResponse.seatbid.bid.crid (batas 128 byte). Materi iklan yang serupa sekalipun harus memiliki nilai unik untuk kolom ini jika berbeda dalam karakteristik penting apa pun, termasuk, tetapi tidak terbatas pada: ukuran, URL yang dideklarasikan, atribut materi iklan, dan jenis vendor. Dengan kata lain, Anda harus memberikan ID materi iklan yang berbeda kepada dua iklan yang:
- Terlihat atau berperilaku berbeda.
- Merender ke gambar yang berbeda.
- Dirender dengan cara yang berbeda (misalnya, satu iklan terdiri dari gambar, sementara iklan lainnya adalah video).
Saat mendesain aplikasi, Anda harus memutuskan cara sistematis untuk membuat ID yang sesuai dengan jenis materi iklan yang ingin Anda kirimkan.
Atribut iklan
Google merekomendasikan untuk mendeklarasikan atribut materi iklan guna mendeskripsikan karakteristik
iklan Anda dan penargetannya menggunakan kombinasi
BidResponse.seatbid.bid.apis dan
BidResponse.seatbid.bid.attr, atau
ekstensi BidResponse.seatbid.bid.ext.attribute. Berikut ini
menjelaskan cara mendeklarasikan atribut:
VPAIDTetapkanBidResponse.seatbid.bid.apiskeVPAID_1, atauVPAID_2. Untuk format JSON, ini dapat ditetapkan ke1atau2.MRAIDTetapkanBidResponse.seatbid.bid.apiskeMRAID_1, atau3untuk format JSON.SIZELESSTetapkanBidResponse.seatbid.bid.attrkeRESPONSIVE, atau18untuk format JSON.PLAYABLEHal ini ditunjukkan dengan menetapkanBidResponse.seatbid.bid.attrkeUSER_INTERACTIVE, atau13untuk format JSON.
Lihat Referensi materi iklan untuk penjelasan tentang cara mendapatkan masukan terkait properti yang terdeteksi dari materi iklan Anda.
Kolom Bidding Terbuka
Respons bid yang dikirim oleh bidder bursa dan jaringan yang berpartisipasi dalam Bidding Terbuka mirip dengan respons bid Authorized Buyers yang berpartisipasi dalam bidding real-time standar. Pelanggan Bidding Terbuka dapat menentukan sejumlah kecil kolom tambahan, dan beberapa kolom yang ada mungkin memiliki penggunaan alternatif. Contoh ini meliputi:
| Kolom | Detail |
|---|---|
BidResponse.imp.pmp.deals.id |
ID transaksi dari namespace bursa yang terkait dengan bid ini dan dilaporkan kepada penayang. |
BidResponse.seatbid.bid.ext.exchange_deal_type |
Jenis transaksi yang dilaporkan kepada penayang, yang memengaruhi cara transaksi diperlakukan dalam lelang. |
BidResponse.seatbid.bid.ext.third_party_buyer_token |
Token yang digunakan untuk mengidentifikasi informasi pembeli pihak ketiga akhir jika bursa sebagai Bidder Bidding Terbuka adalah perantara. ID ini diperoleh dari pembeli pihak ketiga dan harus diteruskan ke Google tanpa diubah dalam respons bid. |
Rekomendasi
- Aktifkan koneksi HTTPS persisten (juga dikenal sebagai "keep-alive" atau "penggunaan ulang koneksi") di server Anda. Tetapkan waktu tunggu minimal 10 detik—nilai yang lebih tinggi akan bermanfaat dalam banyak kasus. Google memverifikasi hal ini selama pengujian latensi awal aplikasi Anda, karena Authorized Buyers mengirimkan permintaan dengan kecepatan tinggi dan perlu menghindari overhead latensi dalam membuat koneksi TCP terpisah untuk setiap permintaan.
Sertakan URL pelacakan tayangan iklan opsional untuk melacak kapan tayangan iklan dirender, bukan saat bidder menang. Karena adanya penurunan antara kemenangan dan rendering, hal ini menghasilkan statistik pelacakan yang lebih akurat.
- Pastikan kode bidder Anda bebas dari dependensi pada kolom yang tidak digunakan lagi, yang dapat menyebabkan bid Anda gagal dengan error.
- Sertakan
BidResponse.seatbid.bid.wdanBidResponse.seatbid.bid.hdalamBidResponseAnda.BidResponseuntuk permintaan yang menyertakan beberapa ukuran iklan harus menyertakan kolom ini atau akan dihapus dari lelang. - Batasi ukuran respons Anda hingga di bawah 8K. Respons yang sangat besar dapat meningkatkan latensi jaringan dan menyebabkan waktu tunggu habis.
- Ikuti panduan untuk bid pada inventaris iOS yang memerlukan atribusi SKAdNetwork.
Contoh respons bid
Contoh berikut menunjukkan contoh permintaan Protobuf dan JSON yang dapat dibaca manusia.
Protobuf OpenRTB
JSON OpenRTB
Penting: Pesan Protobuf yang digambarkan dalam contoh direpresentasikan di sini sebagai teks yang dapat dibaca manusia. Namun, bukan seperti itu pesan dikirim melalui jaringan. Saat menggunakan format Protobuf OpenRTB, hanya pesan BidResponse yang diserialisasi yang akan diterima.
Anda dapat membuat dan melakukan serialisasi pesan BidResponse menggunakan kode C++ berikut:
BidResponse bid_response;
// fill in bid response with bid information
string post_response;
if (bid_response.SerializeToString(&post_response)) {
// respond to the POST with post_response as the content
} else {
// return an error to the POST
}Menentukan materi iklan
Respons bid Anda menentukan materi iklan yang akan ditayangkan jika bid Anda menang. Bid Anda
harus menyertakan salah satu format iklan yang didukung (AMP, video, native). Dalam contoh ini, kita menentukan materi iklan menggunakan kolom html_snippet.
Atau, Anda dapat menentukan materi iklan menggunakan salah satu kolom berikut, berdasarkan format iklan:
- Iklan yang dirender SDK
BidResponse.seatbid.bid.ext.sdk_rendered_ad
- AMP
BidResponse.seatbid.bid.amp_ad_url
- Video
BidResponse.seatbid.bid.adm
- Native
BidResponse.seatbid.bid.adm_native
Tentukan iklan yang dihosting di server Anda sendiri menggunakan cuplikan HTML di kolom BidResponse.seatbid.bid.adm. Cuplikan ini disertakan dalam
iFrame yang disisipkan di halaman web, sehingga iklan diambil dan
dirender saat halaman dimuat. Anda harus membuat cuplikan HTML agar
iklan (banner atau interstisial) dirender dengan benar di dalam iFrame, dan pada
ukuran yang sesuai untuk slot iklan yang Anda ajukan bid.
Selain itu, ukuran iklan yang dideklarasikan dalam respons bid harus sama persis dengan salah satu kombinasi ukuran dalam permintaan bid jika:
- Iklan adalah banner reguler (bukan video, native, atau interstisial).
- Bidder telah mendeklarasikan ukuran dalam respons bid. Pernyataan ukuran diperlukan setiap kali ada lebih dari satu ukuran dalam permintaan.
- Pengecualian dibuat untuk iklan interstisial. Untuk interstisial, lebar harus minimal 50% dari lebar layar dan tinggi minimal 40% dari tinggi layar.
Anda dapat menentukan materi iklan cuplikan HTML menggunakan kode HTML valid apa pun yang dirender dengan benar, tetapi perhatikan batasan dalam menentukan kolom crid di bagian Membuat pesan BidResponse.
Salah satu kegunaannya adalah untuk memasukkan informasi tambahan ke dalam argumen URL yang
diambil dari server Anda sebagai bagian dari rendering iklan. Dengan begitu, Anda dapat meneruskan
data arbitrer tentang tayangan kembali ke server Anda sendiri.
Sebagian besar kebijakan untuk cuplikan HTML yang ditampilkan dalam respons bid sama dengan kebijakan untuk iklan pihak ketiga. Lihat Panduan Program Authorized Buyers, Persyaratan untuk penayangan iklan pihak ketiga, dan Mendeklarasikan URL klik-tayang di iklan untuk mengetahui informasi selengkapnya.
Gunakan URL klik-tayang yang konsisten
URL klik-tayang yang Anda tentukan di kolom BidResponse.seatbid.bid.ext.clickurl harus sama dengan URL halaman landing yang ditentukan dalam materi iklan Anda. Berikut adalah contoh materi iklan dalam format yang didukung yang konsisten dengan kolom clickurl yang ditetapkan ke https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1:
HTML
<div id="my-app-install-ad"
style="font-family: sans-serif; border: 1px solid #ddd; padding: 10px;
display: flex; align-items: center; width: 100%; height: 100%;
box-sizing: border-box; cursor: pointer;"
onclick="window.open('https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1', '_blank')">
<img src="https://example.com/path/to/app_icon.png" alt="App Icon"
style="width: 60px; height: 60px; margin-right: 10px;
border-radius: 8px;">
<div style="flex-grow: 1;">
<h4 style="margin: 0 0 5px 0; font-size: 16px; color: #1a73e8;">
My Awesome App
</h4>
<p style="margin: 0 0 10px 0; font-size: 14px; color: #5f6368;">
The best app for doing awesome things! Download now and get started!
</p>
<span style="background-color: #1a73e8; color: white; padding: 8px 12px;
text-align: center; text-decoration: none;
display: inline-block; border-radius: 4px; font-size: 14px;
font-weight: bold;">Install</span>
</div>
</div>XML VAST
<VAST version="3.0"> <Ad id="creative_id_789"> <InLine> <AdSystem>MyBidderSystem</AdSystem> <AdTitle>My Awesome App Install Video</AdTitle> <Description>Install My Awesome App now!</Description> <Error> <![CDATA[https://tracking.example.com/vast_error?errorcode=[ERRORCODE]]]> </Error> <Impression> <![CDATA[https://tracking.example.com/vast_impression]]> </Impression> <Creatives> <!-- Main Video Creative --> <Creative> <Linear> <Duration>00:00:15</Duration> <TrackingEvents> <Tracking event="start"> <![CDATA[https://tracking.example.com/vast_event?label=start]]> </Tracking> <Tracking event="firstQuartile"> <![CDATA[https://tracking.example.com/vast_event?label=firstQuartile]]> </Tracking> <Tracking event="midpoint"> <![CDATA[https://tracking.example.com/vast_event?label=midpoint]]> </Tracking> <Tracking event="thirdQuartile"> <![CDATA[https://tracking.example.com/vast_event?label=thirdQuartile]]> </Tracking> <Tracking event="complete"> <![CDATA[https://tracking.example.com/vast_event?label=complete]]> </Tracking> </TrackingEvents> <VideoClicks> <ClickThrough id="gplay-video"> <![CDATA[https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1]]> </ClickThrough> <ClickTracking id="bidder-tracker-video"> <![CDATA[https://tracking.example.com/vast_click]]> </ClickTracking> </VideoClicks> <MediaFiles> <MediaFile delivery="progressive" type="video/mp4" width="640" height="360" bitrate="800" scalable="true" maintainAspectRatio="true"> <![CDATA[https://cdn.example.com/myawesomeapp_video.mp4]]> </MediaFile> </MediaFiles> </Linear> </Creative> <!-- Companion Ad Creative --> <Creative> <CompanionAds> <Companion id="companion1" width="300" height="250" assetWidth="300" assetHeight="250"> <StaticResource creativeType="image/png"> <![CDATA[https://cdn.example.com/companion_banner_300x250.png]]> </StaticResource> <TrackingEvents> <Tracking event="creativeView"> <![CDATA[https://tracking.example.com/vast_companion_view]]> </Tracking> </TrackingEvents> <CompanionClickThrough> <![CDATA[https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1]]> </CompanionClickThrough> <CompanionClickTracking> <![CDATA[https://tracking.example.com/vast_companion_click]]> </CompanionClickTracking> </Companion> </CompanionAds> </Creative> </Creatives> </InLine> </Ad> </VAST>
Native
{ "ver": "1.2", "assets": [ { "id": 1, "title": { "text": "My Awesome App" } }, { "id": 2, "img": { "url": "https://example.com/path/to/app_icon.png", "w": 60, "h": 60 } }, { "id": 3, "data": { "value": "The best app for doing awesome things! Download now and get started!" } }, { "id": 4, "data": { "value": "Install" } } ], "link": { "url": "https://play.google.com/store/apps/details?id=com.example.myawesomeapp&referrer=utm_source%3Dgoogle_ab%26utm_medium%3Dcpc%26utm_campaign%3Dinstall_campaign_1", "clicktrackers": [ "https://tracking.example.com/native_click" ] }, "imptrackers": [ "https://tracking.example.com/native_impression" ] }
Menentukan makro
Makro adalah teks berformat yang disematkan ke beberapa kolom respons bid yang berisi URL yang diganti dengan nilai yang relevan pada waktu penayangan iklan. Misalnya,
jika bid yang menang menyertakan makro AUCTION_PRICE dalam materi iklan cuplikan HTML
yang disertakan dengan bid Anda, makro tersebut akan diganti dengan
nilai yang dapat Anda dekripsi untuk menentukan jumlah yang Anda bayar untuk tayangan iklan dalam
lelang.
Anda dapat menyertakan makro di kolom berikut:
-
BidResponse.seatbid.bid.admMakro didukung untuk format XML cuplikan HTML, native, URL video, dan VAST video.
-
BidResponse.seatbid.bid.adm_native.eventtrackers.url -
BidResponse.seatbid.bid.adm_native.imptrackers -
BidResponse.seatbid.bid.ext.amp_ad_urlHanya makro
WINNING_PRICEdanWINNING_PRICE_ESCkhusus Google yang didukung untuk materi iklan AMP. -
BidResponse.seatbid.bid.burl -
BidResponse.seatbid.bid.ext.impression_tracking_urlGunakan ini, bukan
BidResponse.seatbid.bid.burl, jika Anda memerlukan lebih dari satu URL penagihan.
Misalnya, Anda dapat menyertakan makro sebagai bagian dari cuplikan HTML dengan
menyematkan ${MACRO} dalam URL yang digunakan untuk mengambil materi iklan,
dengan MACRO sebagai salah satu makro yang didukung yang dijelaskan dalam
spesifikasi OpenRTB.
Makro Google
Google mendukung makro tambahan selain yang ditemukan dalam spesifikasi OpenRTB. Makro ini diformat secara berbeda, dan akan muncul sebagai %%MACRO%% jika disematkan dalam URL. Tabel berikut menjelaskan
makro ini:
| Makro | Deskripsi |
|---|---|
ADVERTISING_IDENTIFIER |
Memungkinkan pembeli menerima IDFA iOS atau ID Iklan Android pada rendering tayangan iklan. Lihat Mendekripsi ID Pengiklan untuk mengetahui detailnya. |
CACHEBUSTER |
Representasi string dari bilangan bulat empat byte acak, tanpa tanda. |
CLICK_URL_UNESC |
URL klik tanpa konversi karakter untuk iklan. Dalam cuplikan, versi URL klik pihak ketiga yang di-escape harus langsung mengikuti makro. Misalnya, jika URL klik pihak ketiga adalah
<a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> Pada waktu penayangan iklan, ini diperluas menjadi: <a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> URL akan mendaftarkan klik terlebih dahulu ke Google, lalu mengalihkan ke URL klik pihak ketiga. |
CLICK_URL_ESC |
URL klik yang di-escape untuk iklan. Gunakan ini, bukan
Misalnya, kode berikut dapat digunakan dalam cuplikan HTML: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a> Pada waktu penayangan iklan, ini diperluas menjadi: <a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a> Tindakan ini akan mendaftarkan klik dengan Anda dapat menambahkan URL yang di-escape ganda setelah
|
CLICK_URL_ESC_ESC |
URL yang di-escape dua kali untuk iklan. Gunakan ini, bukan
Misalnya, kode berikut dapat digunakan dalam cuplikan HTML: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a> Pada waktu penayangan iklan, ini diperluas menjadi: <a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a> |
SCHEME |
Diperluas ke http: jika permintaan bid tidak memerlukan SSL atau ke https: jika permintaan bid memerlukan SSL. |
SITE |
Domain URL konten yang di-escape URL atau ID anonim untuk inventaris anonim. |
SITE_URL |
Tidak digunakan lagi. Digantikan oleh makro SITE yang menyediakan fungsi yang sama. |
TZ_OFFSET |
Offset zona waktu. |
VERIFICATION |
Nilai yang berbeda untuk produksi dan saat materi iklan dipindai
dalam pipeline verifikasi. Formatnya adalah:
Misalnya, jika materi iklan menyertakan
|
WINNING_PRICE |
Biaya tayangan iklan yang dienkode (yaitu, CPI, bukan CPM) dalam mikro mata uang akun. Misalnya, CPM pemenang sebesar $5 USD
sesuai dengan CPM 5.000.000 micros, atau CPI 5.000 micros. Nilai Untuk mengurai makro ini, Anda harus menerapkan aplikasi yang mendekripsi konfirmasi harga. Lihat halaman Mendekripsi Konfirmasi Harga untuk mengetahui informasi selengkapnya. |
WINNING_PRICE_ESC |
WINNING_PRICE yang di-escape URL. |
Google mewajibkan Anda menggunakan makro CLICK_URL_UNESC atau
CLICK_URL_ESC dalam materi iklan yang ditayangkan oleh pihak ketiga. Google menggunakan makro CLICK_URL untuk pelacakan klik.
Escape URL dalam makro menggunakan skema berikut:
- Karakter spasi diganti dengan tanda plus (
+). - Karakter alfanumerik (0-9, a-z, A-Z) dan karakter dari kumpulan !()*,-./:_~ tidak berubah.
- Semua karakter lainnya diganti dengan
%XX, denganXXadalah angka heksadesimal yang mewakili karakter tersebut.
Pembatasan dan persyaratan penayang
Permintaan bid menyertakan informasi tentang jenis batasan dan persyaratan yang ditetapkan penayang pada materi iklan dalam lelang.
BidRequest.bcat- Anda dapat membandingkan kategori yang diblokir yang ditentukan oleh kolom ini dengan kategori yang
terdeteksi untuk materi iklan yang Anda kirimkan menggunakan kolom
detectedCategoriesReal-time Bidding API.
- Anda dapat membandingkan kategori yang diblokir yang ditentukan oleh kolom ini dengan kategori yang
terdeteksi untuk materi iklan yang Anda kirimkan menggunakan kolom
BidRequest.imp.ext.allowed_vendor_typeBidRequest.imp.secure- Dalam praktiknya, ini akan selalu ditetapkan ke
truekarena Google memerlukan dukungan SSL untuk semua materi iklan.
- Dalam praktiknya, ini akan selalu ditetapkan ke
BidRequest.imp.{audio/banner/native/video}BidRequest.imp.{audio/banner/native/video}.apiBidRequest.imp.{audio/banner/native/video}.battrBidRequest.imp.{audio/banner/video}.mimes
Jangan pernah mengajukan bid dengan iklan yang berisi fitur yang dibatasi. Untuk fitur yang diizinkan
seperti jenis vendor, tampilkan iklan hanya jika jenis vendornya ada dalam
daftar allowed_vendor_type di BidRequest. Hanya format iklan yang ditentukan dalam permintaan bid dengan mengisi kolom seperti BidRequest.imp.banner yang harus disertakan dalam bid Anda. Lihat
komentar untuk kolom ini dalam definisi buffering protokol BidRequest
untuk mengetahui detail selengkapnya.
Jika iklan ditampilkan di BidResponse, Anda harus menetapkan kolom BidResponse.seatbid.bid.attr, BidResponse.seatbid.bid.cat, dan BidResponse.seatbid.bid.adomain atau BidResponse.seatbid.bid.adm_native.link.url secara akurat di BidResponse. Jika iklan memiliki beberapa nilai yang berlaku untuk kolom ini, Anda harus menyertakan setiap nilai. Lihat komentar untuk kolom ini dalam
definisi buffering protokol BidResponse untuk mengetahui detail selengkapnya.
Respons yang tidak menetapkan kolom ini akan dihapus.
Pengukuran Terbuka
Pengukuran Terbuka memungkinkan Anda menentukan vendor pihak ketiga yang menyediakan layanan pengukuran dan verifikasi independen untuk iklan yang ditayangkan ke lingkungan aplikasi seluler.
Format iklan yang didukung mencakup iklan video, banner, dan interstisial. Untuk mengetahui informasi selengkapnya tentang cara menggunakan Pengukuran Terbuka dalam respons bid yang berisi format ini, lihat artikel Pusat Bantuan SDK Pengukuran Terbuka.
Contoh respons bid
Bagian berikut menunjukkan contoh respons bid untuk berbagai jenis iklan.