Setelah aplikasi Anda memproses permintaan bid dari Google, aplikasi tersebut harus membangun dan mengirim respons. Panduan ini menjelaskan cara mengodekan aplikasi Anda untuk membangun responsnya.
Buat pesan BidResponse
Authorized Buyers mengirimkan BidRequest
sebagai isi pesan dari
POST
HTTP. Respons yang dikirimkan aplikasi Anda harus memiliki
header Content-Type
ditetapkan ke application/octet-stream
dan isi pesan yang terdiri dari
buffering protokol serial. Protokol
buffer adalah pesan BidResponse
seperti yang ditentukan dalam
realtime-bidding.proto
. Aplikasi Anda harus mengembalikan file parsable
BidResponse
sebagai respons terhadap setiap BidRequest
. Waktu tunggu
dan respons yang tidak dapat diuraikan dianggap
sebagai error dan throttle Google
bidder kembali dengan
tingkat error yang tinggi.
Jika Anda tidak ingin mengajukan bid pada tayangan iklan, Anda dapat menetapkan
Kolom processing_time_ms
saja, dan membiarkan semua kolom lainnya
kosong. Anda bisa mendapatkan realtime-bidding.proto
dari
data referensi.
ID Materi Iklan
BidResponse
Anda menentukan materi iklan melalui
Kolom buyer_creative_id
(batas 64 byte). Bahkan materi iklan yang mirip
harus memiliki nilai unik untuk buyer_creative_id
jika berbeda
karakteristik penting apa pun, termasuk tetapi tidak terbatas pada: ukuran, URL yang dinyatakan,
atribut materi iklan, dan jenis vendor. Dengan kata lain, Anda harus memberikan
ID materi iklan ke dua iklan yang:
- Terlihat atau berperilaku lain.
- Merender ke gambar yang berbeda.
- Render dengan cara yang berbeda (misalnya, satu iklan terdiri dari gambar, sementara yang lain berisi Flash).
Saat mendesain aplikasi, Anda harus memutuskan cara yang sistematis untuk menghasilkan ID yang sesuai untuk jenis materi iklan yang Anda rencanakan untuk mengirimkan.
Atribut iklan
Anda harus mendeklarasikan atribut materi iklan yang sepenuhnya mendeskripsikan
karakteristik dan penargetannya di BidResponse.Ad.attribute
. Tujuan
yang harus dideklarasikan adalah (lihat juga daftar lengkap atribut
pada
buyer-declarable-creative-attributes.txt):
7 Tagging: IsTagged
Di dalamnya, iklan berisi piksel atau suar web yang bertujuan untuk membuat daftar ID cookie untuk pemasaran ulang berikutnya.8 Remarketing: IsRemarketing
Iklan menargetkan konsumen berdasarkan ID cookie atau ID Perangkat mereka 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 daftar ID cookie atau ID Perangkat mewakili sekumpulan konsumen yang menjadi pembeli didefinisikan sebagai grup minat yang sama.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. Lihat Creatives API untuk penjelasan tentang cara mendapatkan {i>feedback<i} mengenai properti yang terdeteksi pada materi iklan.
34 RichMediaCapabilityType: RichMediaCapabilityFlash
Iklan memerlukan dukungan Flash untuk dirender.50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
Iklan tidak memerlukan Flash untuk dirender.47 RichMediaCapabilityType: RichMediaCapabilitySSL
Iklan dapat ditampilkan di halaman SSL. Perhatikan bahwa Authorized Buyers memperlakukan materi iklan dengan nilai yang dinyatakan berbeda dari atribut ini sebagai berbeda (nilai tersebut akan ditinjau secara terpisah dan memiliki status persetujuan yang berbeda). Oleh karena itu, jika Anda menawar dengan SSL dan materi iklan yang sama versi non-SSL, 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 serupa dengan Authorized Buyers yang berpartisipasi dalam bidding real-time. Pelanggan Bidding Terbuka dapat menentukan tambahan, dan beberapa {i>field<i} yang ada mungkin memiliki penggunaan alternatif. Ini meliputi 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 mengajukan bid 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 yang 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 sebagai Bidder Terbuka adalah perantara. Data ini diperoleh dari pembeli pihak ketiga dan harus diteruskan ke Google tanpa diubah dalam bid yang dihasilkan. |
Rekomendasi
- Mengaktifkan koneksi HTTPS persisten (juga dikenal sebagai "keep-alive" atau "penggunaan ulang koneksi") di server Anda. Atur waktu tunggu menjadi 10 detik pada minimum—nilai yang lebih tinggi akan bermanfaat dalam banyak kasus. Google memverifikasi ini selama tes latensi awal aplikasi, karena Authorized Buyers mengirimkan permintaan dengan kecepatan tinggi dan perlu menghindari {i>overhead<i} latensi ketika membuat koneksi TCP terpisah untuk masing-masing permintaan.
Sertakan URL pelacakan tayangan opsional untuk melacak kapan tayangan iklan dirender, dan bukan saat bidder menang. Karena penurunan yang terjadi antara kemenangan dan rendering, ini menghasilkan pelacakan yang lebih akurat statistik.
- Pastikan kode bidder Anda terbebas dari dependensi pada kolom yang tidak digunakan lagi, yang dapat menyebabkan bid Anda gagal dengan error.
- Sertakan
BidResponse.Ad.width
danBidResponse.Ad.height
diBidResponse
Anda. JBidResponse
untuk permintaan yang menyertakan beberapa ukuran iklan harus menyertakan nilaiwidth
danheight
atau akan tidak diikutsertakan dalam lelang. - Batasi ukuran respons Anda di bawah 8K. Respons yang sangat besar dapat meningkat latensi jaringan dan menyebabkan waktu tunggu habis.
- Ikuti panduan untuk pada inventaris iOS yang memerlukan atribusi SKAdNetwork.
Contoh respons bid
Contoh berikut menampilkan contoh Protobuf yang dapat dibaca manusia dan Permintaan JSON.
JSON OpenRTB
Buffering protokol OpenRTB
Penting: Pesan Protobuf yang digambarkan dalam contoh ditampilkan di sini sebagai teks yang dapat dibaca manusia. Namun, itu bukan cara pesan dikirim melalui kabel. Saat menggunakan Protobuf Google atau OpenRTB hanya pesan BidResponse yang diserialisasi yang akan diterima.
Anda dapat membuat dan menserialisasi 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 Anda menentukan materi iklan yang akan ditayangkan jika bid menang. Bid Anda
harus menyertakan salah satu format iklan yang didukung (AMP, video, native). Di sini
misalnya, kita menentukan materi iklan menggunakan kolom html_snippet
.
Atau, Anda dapat menentukan materi iklan menggunakan salah satu dari 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 menggunakan cuplikan HTML di
kolom html_snippet
dari BidResponse
. Tujuan
cuplikan dimasukkan dalam iFrame yang disisipkan pada halaman web, sehingga iklan
yang diambil dan dirender saat halaman dimuat. Anda harus membuat HTML
agar iklan (banner atau interstisial) dirender dengan benar di dalam
iFrame, dan dengan ukuran yang sesuai untuk slot iklan yang Anda ajukan bid-nya.
Selain itu, ukuran iklan yang dinyatakan dalam respons bid harus sama persis dengan satu kombinasi ukuran dalam permintaan bid ketika:
- Iklan adalah banner biasa (bukan video, native, atau interstisial).
- Bidder telah menyatakan ukuran dalam respons bid. Deklarasi ukuran adalah jika terdapat lebih dari satu ukuran dalam permintaan.
- Ada pengecualian untuk iklan interstisial. Untuk interstisial lebar minimal harus 50% dari lebar layar dan tinggi minimal 40% dari lebar layar tinggi layar.
Kolom html_snippet
mendukung semua kode HTML valid yang
dirender dengan benar, namun perhatikan batasan dalam menentukan
buyer_creative_id
di bagian Buat pesan BidResponse. paket Premium AI
digunakan untuk ini adalah memasukkan informasi tambahan ke dalam argumen URL yang
diambil dari server sebagai bagian dari perenderan iklan. Hal ini memungkinkan Anda meneruskan
data arbitrer tentang tayangan iklan kembali ke server Anda sendiri.
Sebagian besar kebijakan untuk cuplikan HTML yang ditampilkan dalam respons bid sama dengan untuk iklan pihak ketiga. Lihat Authorized Buyers Panduan Program, Persyaratan untuk pihak ketiga penayangan iklan, dan Mendeklarasikan URL klik-tayang di iklan untuk mendapatkan informasi lebih lanjut.
Tentukan makro
Cuplikan HTML yang menentukan materi iklan dapat menyertakan satu atau beberapa materi iklan khusus
konstruksi yang disebut makro. Pada waktu penayangan iklan, nilai diganti dengan
makro. Misalnya, aplikasi bidding klien Anda dapat menggunakan
WINNING_PRICE
untuk menentukan jumlah yang dibayarkan untuk iklan,
jika memenangkan lelang. Untuk menguraikan makro ini, Anda perlu menerapkan
aplikasi yang membongkar enkripsi
konfirmasi harga. Lihat Harga Pendekripsi
Konfirmasi untuk mengetahui informasi selengkapnya.
Menentukan makro sebagai bagian dari cuplikan HTML dalam format
%%MACRO%%
, dengan MACRO
sebagai salah satu ekstensi yang didukung
makro yang tercantum dalam tabel di bawah.
Google mewajibkan Anda menggunakan CLICK_URL_UNESC
atau
Makro CLICK_URL_ESC
dalam materi iklan pihak ketiga yang ditayangkan
. Google menggunakan makro CLICK_URL
untuk pelacakan klik.
Untuk menggunakan makro, sertakan dalam iklan sehingga URL diambil saat
seseorang mengkliknya. Nilai pengambilan yang ditampilkan adalah pengalihan ke pengambilan
URL yang Anda tambahkan ke CLICK_URL
.
Makro | Deskripsi |
---|---|
ADVERTISING_IDENTIFIER |
Memungkinkan pembeli menerima IDFA iOS atau ID Iklan Android pada rendering tayangan. Lihat Mendekripsi ID Pengiklan untuk mengetahui detailnya. |
CACHEBUSTER |
Representasi string dari bilangan bulat empat byte acak yang tidak ditandatangani. |
CLICK_URL_UNESC |
URL klik yang tidak di-escape untuk iklan. Dalam cuplikan tersebut, versi escape dari URL klik pihak ketiga harus langsung mengikuti makro. Misalnya, jika URL klik pihak ketiga
<a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> Pada saat penayangan iklan, ekstensi ini akan diperluas menjadi: <a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> Pertama-tama, URL akan mendaftarkan klik dengan Google, lalu mengalihkan ke URL klik pihak ketiga. |
CLICK_URL_ESC |
URL klik yang di-escape untuk iklan. Gunakan ini sebagai ganti
Misalnya, kode berikut dapat digunakan dalam cuplikan HTML: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a> Pada saat penayangan iklan, ekstensi ini akan 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 ke Anda dapat menambahkan URL yang di-escape ganda setelah
|
CLICK_URL_ESC_ESC |
URL dengan konversi karakter ganda untuk iklan. Gunakan ini sebagai ganti
Misalnya, kode berikut dapat digunakan dalam cuplikan HTML: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a> Pada saat penayangan iklan, ekstensi ini akan 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 |
Diluaskan ke http: jika permintaan bid tidak memerlukan SSL atau untuk
https: jika permintaan bid memerlukan SSL. |
SITE |
Domain yang di-escape URL dari URL konten atau ID anonim untuk inventaris anonim. |
SITE_URL |
Tidak digunakan lagi. Diganti dengan makro SITE yang menyediakan fungsi yang identik. |
TZ_OFFSET |
Offset zona waktu. |
VERIFICATION |
Nilai yang berbeda untuk produksi dan waktu materi iklan dipindai dalam verifikasi
{i>pipelines<i} yang sama. Formatnya adalah: %%?VERIFICATION:true-val:false-val%% dengan
nilai kecuali makro dapat digunakan untuk true-val dan false-val ,
termasuk string kosong. Untuk Bidding Terbuka, sebaiknya bursa menggunakan makro ini;
setelah mereka melakukannya, platform sisi permintaan tidak perlu melakukan perubahan.Misalnya, jika materi iklan menyertakan %%?VERIFICATION:-1:5000%%
maka penggantian teksnya akan menjadi 5000 saat ditayangkan dan -1 di
pipeline verifikasi. Hal ini untuk membantu membedakan antara dua set ping tersebut. |
WINNING_PRICE |
Biaya tayangan yang dienkode (yaitu, CPI, bukan CPM) dalam
mikro mata uang akun. Misalnya, CPM pemenang sebesar $5 USD
sesuai dengan 5.000.000 CPM mikro, atau 5.000 mikro CPI. Fungsi yang didekode
nilai WINNING_PRICE dalam kasus ini adalah 5.000.
Harga yang menang ditentukan dalam CPI.
|
WINNING_PRICE_ESC |
WINNING_PRICE dengan URL yang di-escape. |
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
, denganXX
sebagai heksadesimal angka yang mewakili karakter.
Pembatasan penayang
Penayang menggunakan BidRequest
untuk tidak menerapkan pembatasan pada iklan
mereka izinkan. Anda harus menerapkan pembatasan 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 mengembalikan iklan dengan fitur yang tidak diizinkan. Untuk diizinkan
seperti jenis vendor, mengembalikan iklan hanya jika jenis vendornya ada di
Daftar allowed_vendor_type
di BidRequest
. Lihat
komentar untuk kolom ini dalam buffering protokol BidRequest
definisinya untuk informasi lebih lanjut.
Jika cuplikan HTML ditampilkan di BidResponse
, berarti
yang diperlukan untuk menetapkan attribute
, category
,
dan kolom click_through_url
di BidResponse
.
Jika iklan memiliki beberapa nilai yang berlaku untuk kolom ini, Anda harus
menyertakan setiap nilai. Lihat komentar untuk bidang ini dalam
Definisi buffering protokol BidResponse
untuk detail selengkapnya.
Respons yang belum menetapkan kolom ini akan dihapus.
Kemungkinan nilai BidRequest.excluded_attribute
adalah
(lihat publisher-excludable-creative-attributes.txt):
7 Tagging: IsTagged
Iklan tidak diizinkan jika berisi piksel atau suar web untuk membuat daftar ID cookie untuk pemasaran ulang berikutnya.8 CookieTargeting: IsCookieTargeted
Iklan tidak diizinkan jika menargetkan konsumen berdasarkan ID cookie yang diwakili oleh daftar ID cookie 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 yang diwakili oleh daftar ID cookie sekumpulan konsumen yang ditetapkan pembeli sebagai grup minat yang sama.21 CreativeType: Html
Iklan tidak diizinkan menggunakanhtml_snippet
atausnippet_template
diBidResponse.Ad
.22 CreativeType: VastVideo
Iklan tidak diizinkan menggunakan kolomvideo_url
diBidResponse.Ad
.30 InstreamVastVideoType: Vpaid
Iklan tidak diizinkan memerlukan dukungan VPAID untuk dirender.32 MraidType: MRAID
Iklan tidak diizinkan mewajibkan API MRAID untuk dirender.34 RichMediaCapabilityType: RichMediaCapabilityFlash
Iklan tidak diizinkan memerlukan dukungan Flash untuk dirender.39 RichMediaCapabilityType: RichMediaCapabilityHTML5
Iklan tidak diizinkan mewajibkan fitur HTML5 untuk dirender.48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
Iklan tidak boleh membuat permintaan non-SSL.
Oleh karena itu, jika kolom excluded_attribute
berisi nilai
7, maka Anda tidak boleh menampilkan iklan yang menggunakan piksel atau suar web untuk
membuat daftar. Perhatikan bahwa jika iklan melakukan ini, iklan harus menetapkan nilai 7 di
kolom atribut BidResponse
.
Demikian pula, jika kolom excluded_attribute
berisi nilai 48,
maka Anda hanya boleh menampilkan iklan yang dapat ditampilkan di halaman SSL (dan karenanya
mendeklarasikan atribut 47 RichMediaCapabilityType: RichMediaCapabilitySSL).
Juga kolom excluded_sensitive_category
di
BidRequest
menggunakan kode dari
File ad-sensitive-categories.txt
tersedia di halaman data referensi. Berikut diperpanjang
deskripsi beberapa kode ini:
3 Politics
Mencakup politik atau isu sosial kontroversial; tidak mencakup iklan untuk organisasi berita yang secara umum tidak terkait dengan pandangan yang mendukung pihak tertentu dalam suatu masalah.4 Dating
Mencakup layanan biro jodoh dan komunitas kencan online.5 Religion
Mencakup iklan keagamaan dan iklan yang mendukung atau menentang pandangan keagamaan; tidak mencakup astrologi atau kerohanian non-agamis.7 Video Games (Casual & Online)
Mencakup video game, game online, dan game yang dapat didownload; tidak termasuk konsol video game.8 Ringtones & Downloadables
Add-on seluler mencakup nada dering, dan barang yang dapat didownload seperti screensaver dan wallpaper pada PC dekstop dan tata letak profil serta grafik untuk jejaring sosial.10 Get Rich Quick
Skema yang menjanjikan penghasilan dengan cepat.18 Weight Loss
Mencakup penurun berat badan, diet, serta produk dan program terkait; tidak mencakup iklan makanan sehat atau kebugaran yang umum.19 Cosmetic Procedures & Body Modification
Mencakup pengencangan kulit, sedot lemak, laser, pencabutan dan pemulihan rambut, tato, dan pengubahan bentuk tubuh.23 Drugs & Supplements:
Mencakup farmasi, vitamin, suplemen, dan retailer terkait; tidak termasuk sumber daya yang menyediakan informasi mengenai obat-obatan.24 Sexual & Reproductive Health
Mencakup iklan fungsi seksual dan kesuburan; tidak termasuk sumber daya 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 menunjukkan bagian tubuh manusia yang tersingkap, mulai dari tulang dada sampai pertengahan paha; atau tubuh tertutup pakaian dalam, pakaian renang, lingerie, atau pakaian tembus pandang lainnya atau item non-pakaian seperti handuk atau seprai.37 Sensationalism
Iklan yang bertujuan untuk mendorong pengguna mengklik iklan tersebut dengan cara yang menimbulkan rasa ingin tahu, sering kali menggunakan pesan teaser dengan bahasa atau gambar yang berlebihan. Mencakup iklan yang berfokus pada subjek sensasional (seperti penangkapan, kematian, atau perceraian selebritas) atau bertujuan untuk nilai kejutan.
Pengukuran Terbuka
Pengukuran Terbuka memungkinkan Anda menentukan vendor pihak ketiga yang menyediakan pengukuran independen dan layanan verifikasi untuk iklan yang ditayangkan di lingkungan aplikasi seluler.Format iklan yang didukung saat ini mencakup iklan video, banner, dan interstisial. Untuk informasi lebih lanjut tentang cara menggunakan Pengukuran Terbuka dalam respons bid yang berisi format ini, lihat Pusat Bantuan Open Measurement SDK artikel.
Contoh respons bid
Bagian berikut menunjukkan contoh respons bid untuk berbagai jenis iklan.