Setelah memproses permintaan bid dari Google, aplikasi Anda harus membuat dan mengirimkan respons. Panduan ini menjelaskan cara membuat kode aplikasi untuk membangun respons.
Buat pesan BidResponse
Authorized Buyers mengirimkan BidRequest
sebagai isi pesan
POST
HTTP. Respons yang dikirim aplikasi Anda harus memiliki header Content-Type
yang ditetapkan ke application/octet-stream
dan isi pesan yang terdiri dari buffering protokol serial. Buffering protokol adalah pesan BidResponse
seperti yang didefinisikan dalam realtime-bidding.proto
. Aplikasi Anda harus menampilkan BidResponse
yang dapat diuraikan sebagai respons terhadap setiap BidRequest
. Waktu tunggu dan respons yang tidak dapat diuraikan dianggap error dan Google akan memperlambat bidder dengan tingkat error yang tinggi.
Jika tidak ingin mengajukan bid pada tayangan, Anda dapat menetapkan
kolom processing_time_ms
saja, dan membiarkan semua kolom lainnya
kosong. Anda bisa mendapatkan realtime-bidding.proto
dari
halaman data referensi.
ID Materi Iklan
BidResponse
Anda menentukan materi iklan melalui
kolom buyer_creative_id
(batas 64 byte). Bahkan materi iklan serupa
harus memiliki nilai unik untuk buyer_creative_id
jika materi iklan tersebut
berbeda dalam semua karakteristik penting, 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 untuk dua iklan yang:
- Terlihat atau berperilaku berbeda.
- Merender ke gambar yang berbeda.
- Merender dengan cara yang berbeda (misalnya, satu iklan terdiri dari gambar, sedangkan iklan lainnya berisi Flash).
Saat mendesain aplikasi, Anda harus memutuskan cara sistematis untuk menghasilkan ID yang sesuai untuk jenis materi iklan yang ingin Anda kirim.
Atribut iklan
Anda harus mendeklarasikan atribut materi iklan yang mendeskripsikan sepenuhnya karakteristik
iklan dan penargetannya di BidResponse.Ad.attribute
. Atribut
yang harus dideklarasikan adalah (lihat juga daftar lengkap atribut
yang didukung di
buyer-declarable-creative-attributes.txt):
7 Tagging: IsTagged
Iklan berisi piksel atau suar web yang bertujuan membuat daftar ID cookie untuk pemasaran ulang berikutnya.8 Remarketing: IsRemarketing
Iklan menargetkan konsumen berdasarkan ID cookie atau ID Perangkat mereka dengan daftar ID cookie atau ID Perangkat mewakili sekumpulan konsumen yang sebelumnya berinteraksi dengan situs yang dimiliki atau diwakili oleh pembeli.9 UserInterestTargeting: IsUserInterestTargeted
Iklan menargetkan konsumen berdasarkan ID cookie atau ID Perangkat mereka dengan daftar ID cookie atau ID Perangkat mewakili sekumpulan konsumen yang ditetapkan pembeli sebagai grup minat umum.30 InstreamVastVideoType: Vpaid
Iklan memerlukan dukungan VPAID untuk dirender.32 MraidType: MRAID
Iklan memerlukan API MRAID untuk dirender.
Selain itu, atribut berikut didukung, tetapi deklarasinya tidak diperlukan, karena Authorized Buyers otomatis mendeteksinya, dan akan memblokir (atau mengizinkan) materi iklan berdasarkan nilai yang terdeteksi, bukan deklarasi Anda. Lihat Creatives API untuk penjelasan cara mendapatkan masukan terkait properti materi iklan yang terdeteksi.
34 RichMediaCapabilityType: RichMediaCapabilityFlash
Iklan membutuhkan dukungan Flash untuk merender.50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
Iklan tidak memerlukan Flash untuk dirender.47 RichMediaCapabilityType: RichMediaCapabilitySSL
Iklan memiliki kemampuan untuk ditampilkan pada halaman SSL. Perlu diketahui bahwa Authorized Buyers memperlakukan materi iklan dengan nilai yang dideklarasikan yang berbeda dari atribut ini sebagai berbeda (materi iklan ini akan ditinjau secara terpisah dan memiliki status persetujuan yang berbeda). Oleh karena itu, jika Anda mengajukan bid dengan versi SSL dan non-SSL dari materi iklan yang sama, Anda harus mendeklarasikan atribut ini sebagaimana mestinya, sehingga perbedaan ini tercermin dengan benar di AdX.
Kolom Bidding Terbuka
Respons bid yang dikirim oleh bidder bursa dan jaringan yang berpartisipasi dalam Bidding Terbuka serupa dengan 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. Hal ini mencakup hal berikut:
OpenRTB | Authorized Buyers | Detail |
---|---|---|
BidResponse.imp[].pmp.deals[].id |
BidResponse.ad[].adslot[].exchange_deal_id |
ID transaksi dari namespace bursa yang terkait dengan bid ini dan dilaporkan kepada penayang. |
BidResponse.seatbid[].bid[].ext.exchange_deal_type |
BidResponse.ad[].adslot[].exchange_deal_type |
Jenis transaksi yang dilaporkan kepada penayang, yang memengaruhi cara transaksi diperlakukan dalam lelang. |
BidResponse.seatbid[].bid[].ext.third_party_buyer_token |
BidResponse.ad[].adslot[].third_party_buyer_token |
Token yang digunakan untuk mengidentifikasi informasi pembeli pihak ketiga akhir jika bursa sebagai Bidder Terbuka adalah perantara. Data 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. Setel waktu tunggu minimal ke 10 detik—nilai yang lebih tinggi akan bermanfaat dalam banyak kasus. Google memverifikasi hal ini selama pengujian latensi awal aplikasi Anda karena Authorized Buyers mengirim permintaan dengan kecepatan tinggi dan perlu menghindari overhead latensi saat membuat koneksi TCP terpisah untuk setiap permintaan.
Sertakan URL pelacakan tayangan opsional untuk melacak saat tayangan dirender, bukan saat bidder menang. Karena terjadi penurunan antara kemenangan dan rendering, 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.Ad.width
danBidResponse.Ad.height
dalamBidResponse
Anda.BidResponse
untuk permintaan yang menyertakan beberapa ukuran iklan harus menyertakan nilaiwidth
danheight
atau nilai tersebut akan dihapus dari lelang. - Batasi ukuran respons Anda di bawah 8K. Respons yang sangat besar dapat meningkatkan latensi jaringan dan menyebabkan waktu tunggu habis.
- Ikuti panduan bidding pada inventaris iOS yang memerlukan atribusi SKAdNetwork.
Contoh respons bid
Contoh berikut menampilkan contoh permintaan Protobuf dan JSON yang dapat dibaca manusia.
JSON OpenRTB
Protobuf OpenRTB
Penting: Pesan Protobuf yang digambarkan dalam contoh direpresentasikan di sini sebagai teks yang dapat dibaca manusia. Namun, itu bukanlah cara pesan dikirim melalui kabel. Saat menggunakan format Google atau OpenRTB Protobuf, hanya pesan BidResponse serial 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 }
Tentukan materi iklan
Respons bid 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, kami 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.Ad.sdk_rendered_ad
- AMP
BidResponse.Ad.amp_ad_url
- Video
BidResponse.Ad.video_url
atauBidResponse.Ad.video_vast_xml
- Native
BidResponse.Ad.native_ad
Tentukan iklan yang dihosting di server Anda sendiri menggunakan cuplikan HTML di kolom html_snippet
pada BidResponse
. Cuplikan
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 di-bidding.
Selain itu, ukuran iklan yang dideklarasikan dalam respons bid harus cocok persis dengan salah satu kombinasi ukuran dalam permintaan bid jika:
- Iklan adalah banner biasa (bukan video, native, atau interstisial).
- Bidder telah menyebutkan ukuran dalam respons bid. Deklarasi ukuran diperlukan setiap kali ada lebih dari satu ukuran dalam permintaan.
- Pengecualian dibuat untuk iklan interstisial. Untuk interstisial, lebar minimal harus 50% dari lebar dan tinggi setidaknya 40% dari tinggi layar.
Kolom html_snippet
mendukung semua kode HTML valid yang
dirender dengan benar, tetapi perhatikan batasan dalam menentukan
kolom buyer_creative_id
di bagian Create BidResponse. Salah satu kegunaannya adalah untuk memasukkan informasi tambahan ke dalam argumen URL yang diambil dari server Anda sebagai bagian dari rendering iklan. Hal ini memungkinkan Anda meneruskan
data arbitrer tentang tayangan kembali ke server Anda sendiri.
Sebagian besar kebijakan untuk cuplikan HTML yang ditampilkan di respons bid sama seperti kebijakan untuk iklan pihak ketiga. Lihat Panduan Program Authorized Buyers, Persyaratan untuk penayangan iklan pihak ketiga, dan Mendeklarasikan URL klik-tayang dalam iklan untuk informasi selengkapnya.
Menentukan makro
Cuplikan HTML yang menentukan materi iklan dapat menyertakan satu atau beberapa
konstruksi khusus yang disebut makro. Pada waktu penayangan iklan, nilai akan diganti dengan makro. Misalnya, aplikasi bidding klien dapat menggunakan makro
WINNING_PRICE
untuk menentukan biaya yang dibayarkan untuk iklan,
jika aplikasi memenangkan lelang. Untuk mengurai makro ini, Anda harus mengimplementasikan
aplikasi yang mendekripsi konfirmasi harga. Lihat halaman Konfirmasi Harga Mendekripsi untuk mengetahui informasi selengkapnya.
Tentukan makro sebagai bagian dari cuplikan HTML dalam format
%%MACRO%%
, dengan MACRO
sebagai salah satu makro yang didukung
dan tercantum pada tabel di bawah.
Google mengharuskan Anda menggunakan makro CLICK_URL_UNESC
atau
CLICK_URL_ESC
dalam materi iklan yang ditayangkan
pihak ketiga. Google menggunakan makro CLICK_URL
untuk pelacakan klik.
Untuk menggunakan makro, sertakan makro tersebut dalam iklan sehingga URL akan diambil saat
seseorang mengkliknya. Nilai hasil pengambilan adalah pengalihan ke URL lain yang Anda tambahkan ke CLICK_URL
.
Makro | Deskripsi |
---|---|
ADVERTISING_IDENTIFIER |
Memungkinkan pembeli menerima ID Iklan Android atau IDFA iOS saat rendering tayangan. Lihat Mendekripsi ID Pengiklan untuk mengetahui detailnya. |
CACHEBUSTER |
Representasi string dari bilangan bulat empat byte yang acak dan tidak ditandatangani. |
CLICK_URL_UNESC |
URL klik yang tidak di-escape untuk iklan. Dalam cuplikan, versi yang di-escape dari URL klik pihak ketiga 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 ke: <a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> URL akan mendaftarkan klik dengan Google terlebih dahulu, kemudian 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 ke: <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 dengan konversi karakter ganda setelah |
CLICK_URL_ESC_ESC |
URL dengan konversi karakter ganda 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 ke: <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. Diganti dengan makro SITE yang menyediakan fungsi identik. |
TZ_OFFSET |
Offset zona waktu. |
VERIFICATION |
Nilai yang berbeda untuk produksi dan saat materi iklan dipindai di pipeline
verifikasi. Formatnya adalah: %%?VERIFICATION:true-val:false-val%% dengan
nilai apa pun kecuali makro dapat digunakan untuk true-val dan false-val ,
termasuk string kosong. Untuk Bidding Terbuka, sebaiknya bursa menggunakan makro ini;
setelah melakukannya, platform sisi permintaan tidak perlu membuat perubahan.Misalnya, jika materi iklan akan menyertakan %%?VERIFICATION:-1:5000%% ,
penggantian teksnya adalah 5000 pada penayangan dan -1 dalam
pipeline verifikasi. Hal ini untuk membantu membedakan
kedua kumpulan ping tersebut. |
WINNING_PRICE |
Biaya tayangan yang dienkode (yaitu, CPI, bukan CPM) dalam
mikro mata uang akun. Misalnya, CPM pemenang sebesar $5 USD
setara dengan 5.000.000 CPM mikro, atau 5.000 CPI mikro. Nilai WINNING_PRICE yang didekode dalam kasus ini adalah 5.000.
Harga pemenang ditentukan dalam CPI.
|
WINNING_PRICE_ESC |
WINNING_PRICE dengan escape URL. |
Konversi URL dalam makro menggunakan skema berikut:
- Karakter spasi diganti dengan tanda plus (
+
). - Karakter alfanumerik (0-9, a-z, A-Z) dan karakter dari kumpulan !()*,-./:_~ tetap tidak berubah.
- Semua karakter lainnya akan diganti dengan
%XX
, denganXX
adalah angka heksadesimal yang mewakili karakter tersebut.
Pembatasan penayang
Penayang menggunakan BidRequest
untuk menerapkan pembatasan pada iklan yang akan mereka izinkan. Anda harus menerapkan batasan di kolom berikut:
allowed_vendor_type
excluded_attribute
excluded_sensitive_category
Satu kolom menentukan fitur yang diizinkan untuk iklan dan kolom lainnya menentukan fitur yang tidak diizinkan. Jangan pernah menampilkan iklan dengan fitur yang tidak diizinkan. Untuk fitur yang diizinkan
seperti jenis vendor, tampilkan iklan hanya jika jenis vendornya ada dalam
daftar allowed_vendor_type
di BidRequest
. Lihat komentar untuk kolom ini dalam definisi buffering protokol BidRequest
untuk detail selengkapnya.
Jika cuplikan HTML ditampilkan di BidResponse
, Anda harus menetapkan kolom attribute
, category
, dan click_through_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 detail selengkapnya.
Respons yang tidak menyetel kolom ini akan dihapus.
Nilai BidRequest.excluded_attribute
yang mungkin adalah
(lihat publisher-excludable-creative-attributes.txt):
7 Tagging: IsTagged
Iklan tidak diizinkan jika berisi piksel atau web-beacon yang bertujuan membuat daftar ID cookie untuk pemasaran ulang berikutnya.8 CookieTargeting: IsCookieTargeted
Iklan tidak diizinkan jika menargetkan konsumen berdasarkan ID cookie mereka dengan daftar ID cookie mewakili sekumpulan konsumen yang sebelumnya berinteraksi dengan situs yang dimiliki atau diwakili oleh pembeli.9 UserInterestTargeting: IsUserInterestTargeted
Iklan tidak diizinkan jika menargetkan konsumen berdasarkan ID cookie dengan daftar ID cookie mewakili sekumpulan konsumen yang ditetapkan pembeli sebagai grup minat umum.21 CreativeType: Html
Iklan tidak diizinkan untuk menggunakan kolomhtml_snippet
atausnippet_template
diBidResponse.Ad
.22 CreativeType: VastVideo
Iklan tidak diizinkan untuk menggunakan kolomvideo_url
diBidResponse.Ad
.30 InstreamVastVideoType: Vpaid
Iklan tidak diizinkan untuk memerlukan dukungan VPAID untuk merender.32 MraidType: MRAID
Iklan tidak diizinkan untuk meminta API MRAID untuk dirender.34 RichMediaCapabilityType: RichMediaCapabilityFlash
Iklan tidak diizinkan untuk meminta dukungan Flash agar dapat dirender.39 RichMediaCapabilityType: RichMediaCapabilityHTML5
Iklan tidak diizinkan untuk meminta fitur HTML5 agar dirender.48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
Iklan tidak diizinkan membuat permintaan non-SSL.
Oleh karena itu, jika kolom excluded_attribute
berisi nilai
7, Anda tidak boleh menampilkan iklan yang menggunakan piksel atau web-beacon untuk
membuat daftar. Perhatikan bahwa jika iklan melakukan hal ini, iklan harus menetapkan nilai 7 di
kolom atribut BidResponse
.
Demikian pula, jika kolom excluded_attribute
berisi nilai 48,
Anda hanya boleh menampilkan iklan yang dapat dirender di halaman SSL (dan, sebagaimana mestinya,
deklarasikan atribut 47 RichMediaCapabilityType: RichMediaCapabilitySSL).
Selain itu, kolom excluded_sensitive_category
di BidRequest
menggunakan kode dari file ad-sensitive-categories.txt
yang tersedia di halaman data referensi. Berikut adalah deskripsi lengkap dari beberapa kode tersebut:
3 Politics
Mencakup politik atau masalah sosial kontroversial; tidak termasuk iklan untuk organisasi berita yang secara umum tidak terkait dengan pandangan yang mendukung salah satu partai dalam masalah tertentu.4 Dating
Mencakup layanan kencan dan komunitas kencan online.5 Religion
Mencakup iklan keagamaan dan iklan yang mendukung atau menentang pandangan keagamaan; tidak mencakup astrologi atau sekte kerohanian non-agamis.7 Video Games (Casual & Online)
Mencakup video game, game online, dan game yang dapat didownload; tidak mencakup konsol video game.8 Ringtones & Downloadables
Add-on seluler mencakup nada dering, dan konten digital lainnya yang dapat didownload seperti screensaver dan wallpaper untuk PC desktop dan tata letak profil serta grafik untuk jejaring sosial.10 Get Rich Quick
Skema yang menjanjikan penghasilan yang cepat.18 Weight Loss
Mencakup penurun berat badan, diet, dan produk serta program terkait; tidak termasuk iklan makanan sehat atau kebugaran yang umum.19 Cosmetic Procedures & Body Modification
Mencakup pengencangan kulit, sedotan, laser, pencabutan dan pemulihan rambut, tato, dan modifikasi tubuh.23 Drugs & Supplements:
Mencakup farmasi, vitamin, suplemen, dan retailer terkait; tidak mencakup referensi yang menyediakan informasi mengenai obat-obatan.24 Sexual & Reproductive Health
Mencakup iklan fungsi seksual dan kesuburan; tidak termasuk referensi kehamilan normal.35 Social Casino Games
Mencakup simulasi game perjudian (termasuk, tetapi tidak terbatas pada, poker, slot, bingo, lotre, taruhan olahraga, taruhan pada berbagai balapan, serta game kartu dan game kasino lainnya) di mana tidak ada peluang untuk memenangkan apa pun yang berharga (seperti uang atau hadiah).36 Significant Skin Exposure
Gambar iklan yang tidak memperlihatkan bagian tubuh manusia, mulai dari tulang dada hingga pertengahan paha; atau tubuh mengenakan pakaian dalam, pakaian renang, lingerie, atau pakaian yang tembus pandang atau item non-pakaian lainnya seperti handuk atau seprai.37 Sensationalism
Iklan yang bertujuan untuk mendorong pengguna agar mengklik iklan tersebut dengan cara yang memancing rasa ingin tahu mereka, sering kali menggunakan pesan teaser dengan bahasa atau gambar yang berlebihan. Termasuk iklan yang berpusat pada subjek sensasional (seperti penangkapan, kematian, atau perceraian selebritas) atau bertujuan untuk nilai kejutan.
Pengukuran Terbuka
Open Measurement 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 saat ini mencakup iklan video, banner, dan interstisial. Untuk informasi selengkapnya tentang cara menggunakan Pengukuran Terbuka dalam respons bid yang berisi format ini, lihat artikel Pusat Bantuan Open Measurement SDK.
Contoh respons bid
Bagian berikut menunjukkan contoh respons bid untuk berbagai jenis iklan.