Bangun Responsnya

Setelah memproses permintaan bid dari Google, aplikasi Anda harus membuat dan mengirim respons. Panduan ini menjelaskan cara membuat kode aplikasi untuk membuat respons.

Membuat pesan BidResponse Protobuf

Authorized Buyers mengirimkan BidRequest sebagai isi pesan POST HTTP. Jika endpoint bidding dikonfigurasi untuk menggunakan format Protobuf, aplikasi Anda harus mengirim respons dengan header Content-Type yang ditetapkan ke application/octet-stream dan isi pesan yang terdiri dari buffering protokol serial. Buffer protokol adalah pesan BidResponse seperti yang ditentukan dalam openrtb.proto. Aplikasi Anda harus menampilkan BidResponse yang dapat diuraikan sebagai respons terhadap setiap BidRequest. Waktu tunggu dan respons yang tidak dapat diuraikan dianggap sebagai error dan Google akan membatasi pembeli dengan rasio error tinggi.

Jika tidak ingin mengajukan bid pada tayangan, Anda harus menampilkan respons HTTP 204 kosong. Anda dapat memperoleh openrtb.proto dari halaman data referensi.

ID Materi Iklan

BidResponse Anda menentukan materi iklan melalui kolom BidResponse.seatbid.bid.crid (batas 64 byte). Bahkan materi iklan yang serupa harus memiliki nilai unik untuk kolom ini jika memiliki karakteristik yang berbeda, 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.
  • Dirender dengan cara yang berbeda (misalnya, satu iklan terdiri dari gambar, sedangkan 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 menjelaskan karakteristik iklan dan penargetan menggunakan kombinasi BidResponse.seatbid.bid.apis dan BidResponse.seatbid.bid.attr, atau ekstensi BidResponse.seatbid.bid.ext.attribute. Berikut ini menjelaskan cara mendeklarasikan atribut:

  • VPAID
    Tetapkan BidResponse.seatbid.bid.apis ke VPAID_1, atau VPAID_2. Untuk format JSON, nilai ini dapat disetel ke 1 atau 2.
  • MRAID
    Tetapkan BidResponse.seatbid.bid.apis ke MRAID_1, atau 3 untuk format JSON.
  • SIZELESS
    Tetapkan BidResponse.seatbid.bid.attr ke RESPONSIVE, atau 18 untuk format JSON.
  • PLAYABLE
    Hal ini ditunjukkan dengan menetapkan BidResponse.seatbid.bid.attr ke USER_INTERACTIVE, atau 13 untuk format JSON.

Lihat Referensi materi iklan untuk mendapatkan 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 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 meliputi:

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 Bidding Terbuka adalah perantara. 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 kembali koneksi") di server Anda. Tetapkan 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 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.w dan BidResponse.seatbid.bid.h dalam BidResponse Anda. BidResponse untuk 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 di inventaris iOS yang memerlukan atribusi SKAdNetwork.

Contoh respons bid

Contoh berikut mewakili contoh permintaan Protobuf dan JSON yang dapat dibaca manusia.

Protobuf OpenRTB

JSON OpenRTB

Google

Penting: Pesan Protobuf yang digambarkan dalam contoh direpresentasikan di sini sebagai teks yang dapat dibaca manusia. Namun, cara itulah yang digunakan untuk mengirim pesan melalui jaringan. Saat menggunakan format Protobuf Google atau 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 dengan ukuran yang sesuai untuk slot iklan yang Anda 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, lebarnya harus minimal 50% dari lebar layar dan tingginya minimal 40% dari tinggi layar.

Anda dapat menentukan materi iklan cuplikan HTML menggunakan kode HTML yang valid dan dirender dengan benar, tetapi perhatikan batasan untuk menentukan kolom crid di bagian Buat pesan BidResponse. Salah satu penggunaannya 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 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.

Menentukan makro

Makro adalah teks berformat yang disematkan ke dalam beberapa kolom respons bid yang berisi URL yang diganti dengan nilai yang relevan pada waktu penayangan iklan. Misalnya, jika bid pemenang Anda 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 di lelang.

Anda dapat menyertakan makro di kolom berikut:

  • BidResponse.seatbid.bid.adm

    Makro didukung untuk format cuplikan HTML, native, URL video, dan XML VAST video.

  • BidResponse.seatbid.bid.adm_native.eventtrackers.url

  • BidResponse.seatbid.bid.adm_native.imptrackers

  • BidResponse.seatbid.bid.ext.amp_ad_url

    Hanya makro WINNING_PRICE dan WINNING_PRICE_ESC khusus Google yang didukung untuk materi iklan AMP.

  • BidResponse.seatbid.bid.burl

  • BidResponse.seatbid.bid.ext.impression_tracking_url

    Gunakan 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 menyisipkan ${MACRO} dalam URL yang digunakan untuk mengambil materi iklan, dengan MACRO adalah salah satu makro yang didukung yang dijelaskan dalam spesifikasi OpenRTB.

Makro Google RTB

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 saat rendering tayangan iklan. Lihat Mendekode ID Pengiklan untuk mengetahui detailnya.
CACHEBUSTER Representasi string dari bilangan bulat empat byte acak tanpa tanda tangan.
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 http://my.adserver.com/some/path/handleclick?click=clk, kode berikut dapat digunakan dengan versi URL klik pihak ketiga yang di-escape tunggal setelah pemanggilan makro:

<a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

Pada waktu penayangan iklan, ukuran ini diperluas menjadi:

<a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

URL tersebut akan mendaftarkan klik dengan Google terlebih dahulu, lalu mengalihkan ke URL klik pihak ketiga.

CLICK_URL_ESC

URL klik yang di-escape untuk iklan. Gunakan ini, bukan CLICK_URL_UNESC, jika Anda perlu meneruskan nilai terlebih dahulu melalui server lain yang kemudian akan menampilkan pengalihan.

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, ukuran 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 my.adserver.com yang kemudian akan bertanggung jawab untuk mengalihkan ke URL yang diteruskan dalam parameter google_click_url. Hal ini mengasumsikan bahwa my.adserver.com menghapus awalan escape dari parameter google_click_url.

Anda dapat menambahkan URL yang di-escape ganda setelah %%CLICK_URL_ESC%%. Setelah penghapusan escape dilakukan oleh my.adserver.com, akan ada versi URL yang di-escape tunggal yang ditambahkan ke google_click_url. Saat google_click_url diambil, google_click_url akan menghapus escape satu kali lagi lalu mengalihkan.

CLICK_URL_ESC_ESC

URL yang di-escape ganda untuk iklan. Gunakan ini, bukan CLICK_URL_UNESC jika Anda perlu meneruskan nilai terlebih dahulu melalui server lain yang kemudian akan menampilkan pengalihan.

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, ukuran 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 menjadi http: jika permintaan bid tidak memerlukan SSL atau menjadi https: jika permintaan bid memerlukan SSL.
SITE Domain URL yang di-escape dari URL konten atau ID anonim untuk inventaris anonim.
SITE_URL Tidak digunakan lagi. Diganti dengan makro SITE yang menyediakan fungsi yang sama.
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 melakukan perubahan.

Misalnya, jika materi iklan menyertakan %%?VERIFICATION:-1:5000%%, penggantian teks akan menjadi 5000 saat ditayangkan dan -1 di pipeline verifikasi. Hal ini untuk membantu membedakan antara dua kumpulan ping ini.

WINNING_PRICE

Biaya tayangan iklan yang dienkode (yaitu, CPI, bukan CPM) dalam mikro mata uang akun. Misalnya, CPM pemenang sebesar $5 USD setara dengan 5.000.000 mikro CPM, atau 5.000 mikro CPI. Nilai WINNING_PRICE yang didekode dalam hal ini adalah 5.000. Harga pemenang ditentukan dalam CPI.

Untuk mengurai makro ini, Anda harus menerapkan aplikasi yang mendekripsi konfirmasi harga. Lihat halaman Mendekode 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 iklan yang ditayangkan pihak ketiga. Google menggunakan makro CLICK_URL untuk pelacakan klik.

Pengelakan 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 diganti dengan %XX, dengan XX adalah angka heksadesimal yang mewakili karakter.

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 dikirimkan menggunakan kolom detectedCategories Real-time Bidding API.
  • BidRequest.imp.ext.allowed_vendor_type
  • BidRequest.imp.secure
    • Dalam praktiknya, nilai ini akan selalu ditetapkan ke true karena Google mewajibkan dukungan SSL untuk semua materi iklan.
  • BidRequest.imp.{audio/banner/native/video}
  • BidRequest.imp.{audio/banner/native/video}.api
  • BidRequest.imp.{audio/banner/native/video}.battr
  • BidRequest.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 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.

Banner aplikasi

Protobuf OpenRTB

JSON OpenRTB

Google

Interstisial Aplikasi

Protobuf OpenRTB

JSON OpenRTB

Google

Video interstisial aplikasi

Protobuf OpenRTB

JSON OpenRTB

Google

Native aplikasi

Protobuf OpenRTB

JSON OpenRTB

Google

Video web

Protobuf OpenRTB

JSON OpenRTB

Google

Banner web seluler untuk bidder bursa

Protobuf OpenRTB

JSON OpenRTB