Interaksi bidding real-time dimulai saat Google mengirimkan permintaan bid ke
aplikasi Anda. Panduan ini menjelaskan cara membuat kode aplikasi untuk
memproses permintaan bid.
Uraikan permintaan
Google mengirimkan permintaan bid sebagai buffering protokol serial yang dilampirkan sebagai
payload biner dari permintaan POST HTTP. Content-Type disetel ke
application/octet-stream. Lihat Contoh permintaan bid untuk mengetahui contohnya.
Anda harus mengurai permintaan ini menjadi instance pesan
BidRequest. BidRequest ditentukan dalam realtime-bidding.proto,
yang dapat diperoleh dari halaman data referensi. Anda dapat mengurai pesan
menggunakan metode ParseFromString() di class yang dihasilkan untuk
BidRequest. Misalnya, kode C++ berikut mengurai permintaan
yang diberikan payload POST dalam string:
string post_payload = /* the payload from the POST request */;
BidRequest bid_request;
if (bid_request.ParseFromString(post_payload)) {
// Process the request.
}
Setelah memiliki BidRequest, Anda kemudian dapat menggunakannya sebagai
objek, dengan mengekstrak dan menafsirkan kolom yang diperlukan. Misalnya, di C++:
for (int i = 0; i < bid_request.adslot_size(); ++i) {
const BidRequest_AdSlot& adslot = bid_request.adslot(i);
// Decide what to bid on adslot.
}
Beberapa informasi yang dikirim dalam BidRequest, seperti User-ID, bahasa, atau lokasi geografis Google, tidak selalu tersedia. Jika Anda memiliki
grup iklan pra-penargetan yang menggunakan informasi yang tidak diketahui untuk tayangan
tertentu, grup iklan tersebut tidak akan cocok. Jika informasi yang hilang
tidak penting untuk kondisi pra-penargetan, permintaan bid
akan dikirim dengan menghapus informasi tersebut.
Informasi tentang grup iklan pra-penargetan tersedia di
grup MatchingAdData untuk setiap AdSlot. Kolom ini berisi
ID grup iklan pertama yang cocok dari grup iklan pra-penargetan yang meminta Google
mengirimkan permintaan bid, yaitu grup iklan dan kampanye yang dikenai biaya
jika respons Anda memenangkan lelang tayangan. Dalam keadaan
tertentu, Anda harus secara eksplisit menentukan billing_id untuk
atribusi di BidResponse.AdSlot, misalnya, saat
BidRequest.AdSlot memiliki lebih dari satu matching_ad_data.
Untuk informasi selengkapnya tentang batasan pada konten bid, lihat
realtime-bidding.proto.
File kamus
Permintaan bid menggunakan ID yang ditentukan dalam file kamus, yang tersedia di halaman data referensi.
Makro URL bid
Secara opsional, beberapa kolom BidRequest dapat disisipkan ke
URL yang digunakan dalam permintaan HTTP POST. Hal ini berguna, misalnya, jika Anda menggunakan
frontend ringan yang melakukan load balancing di beberapa backend menggunakan nilai
dari permintaan. Hubungi manajer akun teknis Anda guna meminta dukungan untuk makro baru.
Macro
Deskripsi
%%GOOGLE_USER_ID%%
Diganti dengan google_user_id
dari BidRequest. Misalnya, URL bidder
Permintaan bid yang dikirim ke bidder jaringan dan bursa yang berpartisipasi dalam Bidding
Terbuka mirip dengan Authorized Buyers yang berpartisipasi dalam bidding real-time
standar. Pelanggan Bidding Terbuka akan menerima sejumlah kecil
kolom tambahan, dan beberapa kolom yang ada mungkin memiliki penggunaan alternatif. Hal ini
mencakup hal-hal berikut:
OpenRTB
Authorized Buyers
Detail
BidRequest.imp[].ext.dfp_ad_unit_code
BidRequest.adslot[].dfp_ad_unit_code
Berisi kode jaringan Ad Manager penayang yang diikuti dengan hierarki
unit iklan, yang dipisahkan dengan garis miring.
Contohnya, ini akan muncul dengan format yang mirip dengan:
/1234/cruises/mars.
BidRequest.user.data[].segment[]
BidRequest.adslot[].exchange_bidding.key_value[]
Pasangan nilai kunci berulang yang dikirim dari penayang ke bidder bursa.
Anda dapat menentukan bahwa nilai tersebut adalah key-value pair yang dikirim oleh
penayang saat BidRequest.user.data[].name ditetapkan ke
“Publisher Passed”.
Mendeklarasikan vendor yang diizinkan
Vendor teknologi yang menyediakan layanan seperti riset, pemasaran ulang, dan
penayangan iklan dapat berperan dalam interaksi antara pembeli dan penjual. Hanya
vendor yang telah diperiksa oleh Google terkait partisipasi dalam interaksi
Authorized Buyers yang diizinkan.
Untuk memahami BidRequest dan membuat
BidResponse, Anda harus mengetahui dua kemungkinan
yang berbeda untuk mendeklarasikan vendor teknologi:
Vendor lain hanya dapat berpartisipasi jika dideklarasikan di
BidRequest dan BidResponse:
Di BidRequest, kolom allowed_vendor_type
menentukan vendor yang diizinkan penjual. Vendor yang akan dikirim di
kolom allowed_vendor_type dari BidRequest
tercantum dalam file kamus
Vendors.txt.
Di BidResponse, kolom vendor_type
menentukan vendor yang diizinkan yang ingin digunakan oleh pembeli.
Contoh permintaan bid
Contoh berikut menunjukkan contoh permintaan Protobuf dan JSON yang dapat dibaca manusia.
Untuk mengonversi permintaan bid menjadi bentuk biner, seperti yang Anda dapatkan dari payload POST dalam permintaan nyata, Anda dapat melakukan hal berikut (di C++). Namun, perlu diperhatikan bahwa ini tidak berlaku untuk JSON OpenRTB.
string text_format_example = /* example from above */;
BidRequest bid_request;
if (TextFormat::ParseFromString(text_format_example, &bid_request)) {
string post_payload;
if (bid_request.SerializeToString(&post_payload)) {
// post_payload is a binary serialization of the protocol buffer
}
}
Pemasaran Ulang
Authorized Buyers meneruskan ID iklan seluler dalam permintaan bid dari
aplikasi seluler. ID iklan seluler dapat berupa
IDFA iOS atau
ID iklan Android, yang dikirim melalui makro
%%EXTRA_TAG_DATA%% di tag JavaScript yang dikelola oleh
Authorized Buyers.
Makro %%ADVERTISING_IDENTIFIER%% memungkinkan pembeli menerima
IDFA iOS atau ID Iklan Android pada rendering tayangan. Metode ini menampilkan
buffer proto terenkripsi MobileAdvertisingId seperti
%%EXTRA_TAG_DATA%%:
Anda dapat membuat daftar pengguna dari ID periklanan seluler menggunakan ID iklan yang telah Anda kumpulkan selama rendering tayangan. Daftar pengguna ini dapat dikelola
di server Anda atau di kami. Untuk membuat daftar pengguna di server Google, Anda
bisa menggunakan fasilitas upload massal kami.
Jika ID periklanan seluler cocok dengan daftar pengguna, Anda dapat menggunakannya untuk menjalankan
pemasaran ulang.
Masukan real-time
Masukan real-time tersedia untuk Authorized Buyers, serta
bursa dan jaringan yang menggunakan Bidding Terbuka.
Masukan respons bid didukung pada permintaan bid berikutnya untuk
AdX Protocol dan OpenRTB. Untuk OpenRTB, kode ini dikirim dalam BidRequestExt.
Selain kolom default yang dikirim dalam Masukan Respons Bid, Anda juga dapat mengirim data kustom dalam respons bid (baik Proto AdX atau OpenRTB) menggunakan event_notification_token yang ditampilkan di BidResponse. event_notification_token adalah
data arbitrer yang hanya diketahui oleh bidder yang mungkin membantu proses debug, misalnya: ID penargetan atau ID bidding baru yang mewakili taktik baru, atau
metadata yang terkait dengan materi iklan yang hanya diketahui oleh bidder. Untuk mengetahui detailnya,
lihat Buffering Protokol Ekstensi
OpenRTB untuk RTB dan AdX Proto
untuk AdX.
Saat Authorized Buyers mengirimkan permintaan bid ke bidder, bidder akan membalas
dengan BidResponse. Jika bidder mengaktifkan masukan real-time,
dalam permintaan bid berikutnya, Authorized Buyers akan mengirimkan masukan tentang
respons tersebut dalam pesan BidResponseFeedback, seperti yang ditunjukkan di bawah:
message BidResponseFeedback {
// The unique id from BidRequest.id
optional bytes request_id = 1;
// The index of the BidResponse_Ad if there was more than one. The index
// starts at zero for the first creative.
optional int32 creative_index = 2;
// The status code for the ad. See creative-status-codes.txt in the
// technical documentation for a list of ids.
optional int32 creative_status_code = 3;
// If the bid won the auction, this is the price paid in your account
// currency. If the bid participated in the auction but was out-bid, this
// is the CPM that should have been exceeded in order to win. This is not
// set if the bid was filtered prior to the auction, if the publisher or
// winning bidder has opted out of price feedback or if your account has
// opted out of sharing winning prices with other bidders. For first-price
// auctions, minimum_bid_to_win is populated instead of this field.
optional int64 cpm_micros = 4;
// The minimum bid value necessary to have won the auction, in micros of
// your account currency. If your bid won the auction, this is the second
// highest bid that was not filtered (including the floor price). If your
// bid did not win the auction, this is the winning candidate's bid. This
// field will only be populated if your bid participated in a first-price
// auction, and will not be populated if your bid was filtered prior to the
// auction.
optional int64 minimum_bid_to_win = 7;
// The minimum bid value necessary to have won the server-side component of
// the overall auction given that there was also an interest group bidding
// component to the overall auction which ran using the Protected Audience
// API. The value is expressed in CPM micros of the buyer account currency.
// The minimum bid to win for the overall auction, including bids from the
// server-side and the on-device interest group components, is populated in
// the minimum_bid_to_win field of the same BidResponseFeedback object.
optional int64 server_side_component_minimum_bid_to_win = 16;
// Billable event rate multiplier that was applied to this bid during
// ranking. The adjustment reflects the likelihood that your bid would
// generate a billable event (namely, the ad renders successfully) if it won
// the auction, relative to the probability that other bids generate a
// billable event if they won the auction. This adjustment can be larger or
// smaller than 1. This affects the final ranking in the auction only; in
// particular, this multiplier does not affect the payment or whether the
// bid clears any floor price.
optional float billable_event_rate_bid_adjustment = 15 [default = 1];
// When a publisher uses an RTB auction and waterfall-based SDK mediation on
// the same query, the winner of the real-time auction must also compete in
// a mediation waterfall (which is ordered by price) to win the impression.
// If the bid participated in the auction and there was no waterfall, the
// value of this field is 0. If the bid participated in the auction and
// there was a waterfall, the value of this field is a price representing a
// sample bid from the eligible mediation networks that were higher than the
// auction winner, weighted by expected fill rate. This field can be used
// in conjunction with minimum_bid_to_win to train bidding models. The CPM
// is in micros of your account currency.
optional int64 sampled_mediation_cpm_ahead_of_auction_winner = 10;
// Event notification token that was included in the bid response.
optional bytes event_notification_token = 5;
// Buyer creative ID that was included in the bid response.
optional string buyer_creative_id = 6;
// Possible types of bid response feedback objects.
enum FeedbackType {
FEEDBACK_TYPE_UNSPECIFIED = 0;
// Feedback for a bid that was submitted on a bid response.
BID_FEEDBACK = 1;
// Feedback for an interest group buyer submitted on a bid response to
// particpate in an interest group bidding component of the auction run
// using the Protected Audience API.
INTEREST_GROUP_BUYER_FEEDBACK = 2;
}
// The type of the BidResponseFeedback message. Google will send separate
// BidResponseFeedback objects for:
// a) Each bid submitted on a bid response
// b) Each buyer submitted on a bid response to particpate in an interest
// group bidding component of the auction run using the Protected Audience
// API.
optional FeedbackType feedback_type = 17;
// Origin of an interest group buyer that was included in the bid response.
// This field is populated only for feedback where a bidder opted in an
// interest group buyer to participate in the interest group bidding
// component of the overall auction run using the Protected Audience API.
// To learn more about origins, see https://www.rfc-editor.org/rfc/rfc6454.
// To learn more about interest group bidding and the Protected Audience
// API, see
// https://developers.google.com/authorized-buyers/rtb/fledge-origin-trial.
optional string buyer_origin = 18;
// The status code for the submitted interest group buyer. This field is
// only populated in the feedback for an interest group buyer that a bidder
// requested to enter into the interest group auction through the bid
// response. Individual creative status codes of bids submitted by the buyer
// in the on-device interest group auction are not available. See
// https://storage.googleapis.com/adx-rtb-dictionaries/interest-group-buyer-status-codes.txt
// for a list of interest group buyer status codes.
optional int32 interest_group_buyer_status_code = 19;
}
Dari pesan ini, kolom pertama yang harus Anda periksa adalah
bid_response_feedback.creative_status_code; Anda dapat menemukan
arti kode di
creative-status-codes.txt. Perhatikan bahwa jika memenangkan bid, Anda dapat memilih tidak ikut
dari masukan harga. Untuk informasi selengkapnya, lihat Cara memilih tidak ikut.
Masukan real-time menyertakan ID permintaan bid dan salah satu hal berikut:
Hasil lelang
Masukan real-time
Pembeli tidak mengajukan bid.
Tidak ada.
Pembeli mengirimkan bid yang difilter sebelum mencapai
lelang.
Setelah mengajukan bid di lelang harga pertama, Anda akan menerima masukan
real-time termasuk kolom minimum_bid_to_win dan
sampled_mediation_cpm_ahead_of_auction_winner jika bid
tidak difilter dari lelang. Sinyal ini dapat digunakan untuk memberi tahu
logika bidding Anda tentang seberapa tinggi atau lebih rendah bid Anda agar dapat
memenangkan tayangan.
minimum_bid_to_win: Bid minimum yang dapat
ditempatkan untuk memenangkan lelang bidding real-time. Jika Anda memenangkan lelang, ini akan menjadi
bid terendah yang dapat Anda ajukan sambil tetap menang. Jika Anda kalah dalam
lelang, ini akan menjadi bid pemenang.
sampled_mediation_cpm_ahead_of_auction_winner: Jika ada
jaringan lain dalam rantai mediasi, nilai
kolom ini adalah harga yang mewakili bid contoh dari salah satu
jaringan mediasi yang memenuhi syarat dan lebih tinggi dari pemenang lelang, yang diukur
berdasarkan rasio pengisian yang diharapkan. Nilai ini akan ditetapkan ke 0 jika tidak ada jaringan dalam
rantai mediasi yang diperkirakan akan terisi, atau jika penayang tidak menggunakan mediasi
SDK.
Cara kerjanya
Guna menjelaskan penghitungan yang digunakan untuk menentukan kemungkinan nilai
untuk minimum_bid_to_win dan
sampled_mediation_cpm_ahead_of_auction_winner, kita harus terlebih dahulu
menentukan hal berikut:
Berikut adalah CPM dalam rantai mediasi dalam urutan menurun:
\[C_1, C_2, …, C_n\]
Hal berikut menunjukkan rasio pengisian yang sesuai untuk CPM di
rantai mediasi:
\[f_1, f_2, …, f_n\]
Berikut adalah fungsi yang digunakan untuk menentukan CPM yang diharapkan dan
probabilitasnya dari elemen rantai mediasi \(i\), berdasarkan rasio pengisian
yang diberikan:
\(X_i = \{C_i\) dengan probabilitas \(f_i\); \(0\) dengan probabilitas \(1 - f_i\}\)
Rantai mediasi pemenang akhir adalah:
\[\{C_1, C_2, …, C_K, W\}\]
dengan \(W\) bid pemenang, dan \(C_K > W >= C_{K+1}\)
Harga minimum, atau minimum, dilambangkan sebagai \(F\).
Bid kedua ditunjukkan sebagai \(R\).
Penghitungan untuk pemenang lelang
Kolom
Perhitungan
minimum_bid_to_win
\(max\{F, R, X_{K+1}, …, X_n\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(\{C_i\) dengan probabilitas \(\prod_{j=1}^{i-1}(1-f_j) \cdot f_i \div \prod_{j=1}^{K}(1-f_j)\}\)
Untuk \(1 <= i <= K\).
Penghitungan untuk pecundang lelang
Kolom
Perhitungan
minimum_bid_to_win
\(max\{F, W\}\)
sampled_mediation_cpm_ahead_ of_auction_winner
\(max\{X_1, …, X_K\}\)
Contoh dengan rantai mediasi sederhana
Asumsikan penayang menggunakan bidding real-time dan rantai mediasi SDK sebagai
berikut:
Rantai Mediasi SDK
CPM yang diharapkan
Rasio Pengisian
Jaringan 1
\(C_1 = $3.00\)
\(f_1 = 5\%\)
Jaringan 2
\(C_2 = $2.00\)
\(f_2 = 45\%\)
Jaringan 3
\(C_3 = $0.50\)
\(f_3 = 80\%\)
Jaringan 4
\(C_4 = $0.10\)
\(f_4 = 85\%\)
Asumsikan hal berikut sebagai hasil dari lelang RTB:
Lelang RTB
CPM
Pemenang Lelang (M)
$1,00
Juara Lelang (R)
$0,05
Harga Reservasi / Lantai (F)
$0
Bid yang memenangkan lelang
Berikut adalah contoh penghitungan nilai dan probabilitas untuk
minimum_bid_to_win dan
sampled_mediation_cpm_ahead_of_auction_winner untuk
bid yang menang.
Berikut adalah contoh cara penghitungan nilai dan probabilitas untuk
minimum_bid_to_win dan
sampled_mediation_cpm_ahead_of_auction_winner untuk
bid yang kalah.
minimum_bid_to_win
Probability
\(max(F, W) = $1.00\)
\(100\%\)
sampled_mediation_cpm_ ahead_of_auction_winner
Probability
\(C_1 = $3.00\)
\(f_1 = 5\%\)
\(C_2 = $2.00\)
\((1-f_1) \cdot f_2 =~ 42.8\%\)
\(0\)
\((1-f_1) \cdot (1-f_2) =~ 52.2\%\)
Perataan bid
Perataan bid menjelaskan pemrosesan satu BidRequest
kompleks menjadi beberapa permintaan bid yang dikirim ke
aplikasi Anda. Karena ID ini mempertahankan ID yang identik (BidRequest.google_query_id di Protokol RTB Authorized Buyers atau BidRequestExt.google_query_id di protokol OpenRTB), Anda dapat menentukan permintaan bid mana yang dikorelasikan setelah diratakan.
Format iklan
Beberapa peluang iklan dapat menerima beberapa format. Dengan perataan bid, setiap
format dikirim dalam permintaan bid yang berbeda dengan atribut seperti ID penagihan
yang memenuhi syarat relevan dengan format yang ditentukan dalam permintaan.
Permintaan bid yang berisi format berikut akan disatukan menjadi permintaan bid yang berbeda:
Banner
Video
Audio
Native
Contoh perataan format iklan
Berikut adalah contoh yang menampilkan permintaan bid JSON OpenRTB yang disederhanakan tanpa perataan
format iklan jika dibandingkan dengan kumpulan permintaan yang diratakan yang setara:
Peluang iklan untuk bidder tertentu dapat berlaku untuk berbagai jenis
transaksi, selain lelang terbuka. Dengan pemisahan bid untuk transaksi, satu permintaan
bid akan dikirim untuk lelang terbuka, dan satu untuk setiap jenis transaksi
harga tetap. Dalam praktiknya, batasan iklan dapat berbeda antara lelang dan jenis transaksi
harga tetap, misalnya, untuk peluang iklan video tertentu yang tersedia untuk
lelang terbuka dan transaksi harga tetap, bidder akan menerima permintaan bid
yang berbeda untuk setiap lelang jika batasan seperti durasi iklan maksimum dan apakah
iklan yang dapat dilewati diizinkan dapat berbeda. Akibatnya, perataan yang diterapkan pada peluang
iklan memungkinkan Anda lebih mudah membedakan batasan iklan untuk lelang
terbuka dan kesepakatan harga tetap.
Durasi video maksimum yang dapat dilewati
Protokol Google dan penerapan OpenRTB mendukung kolom berikut untuk durasi video dan kemampuan untuk dilewati:
Durasi
Durasi yang dapat dilewati
Dapat dilewati
Protokol Google
max_ad_duration
skippable_max_ad_duration
video_ad_skippable
OpenRTB
maxduration
t/a
skip
Artinya, meskipun protokol Google dapat memiliki durasi terperinci yang dapat dilewati dan tidak dapat dilewati, penerapan OpenRTB hanya memiliki satu nilai durasi maksimum.
Sebelum pemisahan bid, maxduration OpenRTB akan ditetapkan ke
bagian bawah kolom max_ad_duration dan
skippable_max_ad_duration protokol Google. Perilaku ini sekarang telah berubah menjadi
mengirim dua permintaan bid terpisah jika nilai ini berbeda: satu mewakili
maxduration untuk dapat dilewati dan yang lain untuk peluang
yang tidak dapat dilewati.
Contoh berikut menunjukkan cara permintaan protokol Google diterjemahkan
ke OpenRTB sebelum dan sesudah bid merata. Permintaan protokol Google yang setara memiliki max_ad_duration15 dan skippable_max_ad_duration60.
Contoh
max_ad_duration
skip (benar ATAU salah)
Permintaan asli tanpa perataan
15
true
Permintaan diratakan #1: Tidak dapat dilewati
15
false
Permintaan diratakan #2: Dapat dilewati
60
true
Perataan permintaan bid durasi video yang dapat dilewati hanya akan dilakukan jika ketentuan berikut terpenuhi:
Permintaan tersebut mengizinkan video.
Video yang boleh dilewati dan tidak boleh dilewati diizinkan, dengan nilai masing-masing durasi maksimal
yang berbeda.
Permintaan ini memenuhi syarat untuk Lelang Pribadi atau Lelang Terbuka.
Akun bidder memiliki endpoint OpenRTB yang aktif.
Anda dapat memilih untuk tidak menggunakan jenis perataan ini dengan menghubungi manajer akun teknis Anda.
Pod video
Permintaan bid untuk pod video dengan beberapa peluang iklan diratakan,
sehingga setiap permintaan bid ditujukan untuk peluang iklan tunggal dari pod tersebut.
Dengan demikian, Anda dapat mengajukan bid pada beberapa peluang iklan untuk pod tertentu.
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.
Anda dapat menentukan apakah penayang mendukung Pengukuran Terbuka dalam permintaan
bid dengan memeriksa apakah peluang iklan mengecualikan atribut OmsdkType:
OMSDK 1.0 yang ditemukan dalam Atribut materi iklan
yang dapat dikecualikan penayang. Untuk protokol Authorized Buyers, ini dapat
ditemukan di bagian BidRequest.adslot[].excluded_attribute. Untuk protokol OpenRTB, ini akan ditemukan pada atribut battr untuk Banner atau Video, tergantung pada formatnya.
Untuk informasi selengkapnya tentang cara menafsirkan permintaan bid yang berisi sinyal Pengukuran
Terbuka, lihat artikel Pusat Bantuan SDK Pengukuran
Terbuka.
Contoh permintaan bid
Bagian berikut menunjukkan contoh permintaan bid untuk berbagai jenis iklan.