การโต้ตอบในการเสนอราคาแบบเรียลไทม์จะเริ่มขึ้นเมื่อ Google ส่งคำขอราคาเสนอไปยังแอปพลิเคชันของคุณ คู่มือนี้จะอธิบายวิธีเขียนโค้ดของแอปพลิเคชันเพื่อประมวลผลคำขอราคาเสนอ
แยกวิเคราะห์คำขอ
Google จะส่งคำขอราคาเสนอเป็นบัฟเฟอร์โปรโตคอลอนุกรมที่แนบมาเป็นเพย์โหลดไบนารีของคำขอ HTTP POST ตั้งค่า Content-Type
เป็น application/octet-stream
โปรดดูตัวอย่างตัวอย่างคำขอราคาเสนอ
คุณต้องแยกวิเคราะห์คำขอนี้เป็นอินสแตนซ์ของข้อความ BidRequest
BidRequest
กำหนดไว้ใน realtime-bidding.proto
ซึ่งหาได้จากหน้าข้อมูลอ้างอิง คุณแยกวิเคราะห์ข้อความได้โดยใช้เมธอด ParseFromString()
ในคลาสที่สร้างขึ้นสำหรับ BidRequest
ตัวอย่างเช่น โค้ด C++ ต่อไปนี้แยกวิเคราะห์คำขอโดยมีเพย์โหลด POST ในสตริง
string post_payload = /* the payload from the POST request */; BidRequest bid_request; if (bid_request.ParseFromString(post_payload)) { // Process the request. }
เมื่อมี BidRequest
แล้ว คุณจะใช้งานรายการนี้เป็นออบเจ็กต์เพื่อดึงข้อมูลและตีความช่องที่ต้องการได้ ตัวอย่างเช่น ใน
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. }
ข้อมูลบางอย่างที่ส่งใน BidRequest
เช่น รหัสผู้ใช้ Google
ภาษา หรือสถานที่ตั้งทางภูมิศาสตร์ อาจไม่พร้อมใช้งานเสมอไป หากคุณมี
การกำหนดเป้าหมายกลุ่มโฆษณาล่วงหน้าที่ใช้ข้อมูลที่ไม่รู้จักสำหรับการแสดงผลหนึ่งๆ กลุ่มโฆษณาเหล่านั้นจะไม่ตรงกัน ในกรณีที่ข้อมูลที่ขาดหายไปดังกล่าวไม่สำคัญกับเงื่อนไขการกำหนดเป้าหมายล่วงหน้า ระบบจะส่งคำขอราคาเสนอพร้อมข้อมูลดังกล่าว
ข้อมูลเกี่ยวกับกลุ่มโฆษณาของการกำหนดเป้าหมายล่วงหน้าจะอยู่ในกลุ่ม MatchingAdData
สำหรับแต่ละ AdSlot
ไฟล์นี้ประกอบด้วยรหัสกลุ่มโฆษณากลุ่มแรกของกลุ่มโฆษณาที่กำหนดเป้าหมายล่วงหน้าซึ่งแจ้งให้ Google ส่งคำขอราคาเสนอ กล่าวคือ กลุ่มโฆษณาและแคมเปญที่เรียกเก็บเงินหากการตอบกลับของคุณชนะการประมูลสำหรับการแสดงผล ในบางสถานการณ์ คุณต้องระบุ billing_id
อย่างชัดแจ้งสำหรับการระบุแหล่งที่มาใน BidResponse.AdSlot
ตัวอย่างเช่น เมื่อBidRequest.AdSlot
มีmatching_ad_data
มากกว่า 1 รายการ
ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อจำกัดของเนื้อหาของราคาเสนอได้ที่ realtime-bidding.proto
ไฟล์พจนานุกรม
คำขอราคาเสนอใช้ตัวระบุที่กำหนดไว้ในไฟล์พจนานุกรม ซึ่งมีอยู่ในหน้าข้อมูลอ้างอิง
มาโคร URL การเสนอราคา
คุณสามารถแทรกช่องบางช่องของ BidRequest
ลงใน URL ที่ใช้ในคำขอ HTTP POST ได้ วิธีนี้มีประโยชน์ เช่น หากคุณใช้ฟรอนท์เอนด์ขนาดเล็กที่มีการจัดสรรภาระงานผ่านแบ็กเอนด์หลายรายการโดยใช้ค่าจากคำขอ ติดต่อผู้จัดการลูกค้าด้านเทคนิคเพื่อขอรับการสนับสนุนสำหรับมาโครใหม่
Macro | คำอธิบาย |
---|---|
%%GOOGLE_USER_ID%% |
แทนที่ด้วย http://google.bidder.com/path?gid=%%GOOGLE_USER_ID%%จะถูกแทนที่ด้วย http://google.bidder.com/path?gid=dGhpyBhbiBleGFtGxlในเวลาของคำขอ หากไม่ทราบ User ID ของ Google สตริงว่างจะถูกแทนที่ด้วยผลลัพธ์ที่คล้ายกับ http://google.bidder.com/path?gid= |
%%HAS_MOBILE%% |
แทนที่ด้วย |
%%HAS_VIDEO%% |
แทนที่ด้วย |
%%HOSTED_MATCH_DATA%% |
แทนที่ด้วยค่าของช่อง |
%%MOBILE_IS_APP%% |
แทนที่ด้วย |
ค้นหารหัสแอปบนอุปกรณ์เคลื่อนที่จาก URL ธุรกรรม
ธุรกรรมจากแอปพลิเคชันบนอุปกรณ์เคลื่อนที่จะรายงาน URL ที่มีลักษณะดังนี้
mbappgewtimrzgyytanjyg4888888.com
ใช้ตัวถอดรหัส base-32 เพื่อถอดรหัสส่วนของสตริงเป็นตัวหนา (gewtimrzgyytanjyg4888888
)
คุณใช้ตัวถอดรหัสออนไลน์ได้ แต่ต้องใช้อักษรตัวพิมพ์ใหญ่และแทนที่ 8
ด้วยค่า =
ดังนั้นเมื่อถอดรหัสค่านี้
GEWTIMRZGYYTANJYG4======จะได้ผลลัพธ์ดังนี้
1-429610587สตริง
429610587
คือรหัสแอปสำหรับแอป iOS
iFunny
นี่เป็นอีกตัวอย่างหนึ่ง URL ที่รายงานคือ
mbappgewtgmjug4ytmmrtgm888888.comถอดรหัสค่านี้:
GEWTGMJUG4YTMMRTGM======ผลลัพธ์ใน
1-314716233ผลลัพธ์
314716233
คือรหัสแอปสำหรับแอป iOS
TextNow
ค้นหาชื่อแอปบนอุปกรณ์เคลื่อนที่จาก URL ธุรกรรม
ต่อไปนี้คือตัวอย่างการใช้ชื่อแอป URL ที่รายงานมีลักษณะดังนี้
mbappMFUXELTDN5WS42DZOBQWQLTJN4XHG3DJORUGK4Q888.comถอดรหัสค่านี้
MFUXELTDN5WS42DZOBQWQLTJN4XHG3DJORUGK4Q===ผลลัพธ์จะเป็น
air.com.hypah.io.slitherผลลัพธ์จะเท่ากับแอป Android slither.io
ช่องของการเสนอราคาแบบเปิด
คำขอราคาเสนอที่ส่งไปยัง Exchange และผู้เสนอราคาเครือข่ายที่เข้าร่วมในการเสนอราคาแบบเปิดนั้นคล้ายกับคำขอราคาเสนอของ Authorized Buyers ที่มีส่วนร่วมในการเสนอราคาแบบเรียลไทม์มาตรฐาน ลูกค้าในการเสนอราคาแบบเปิดจะได้รับช่องเพิ่มเติมเล็กน้อย และช่องที่มีอยู่อีก 2-3 ช่องอาจมีการใช้งานที่เป็นทางเลือก ซึ่งรวมถึงเนื้อหาต่อไปนี้
OpenRTB | Authorized Buyers | รายละเอียด |
---|---|---|
BidRequest.imp[].ext.dfp_ad_unit_code |
BidRequest.adslot[].dfp_ad_unit_code |
มีรหัสเครือข่าย Ad Manager ของผู้เผยแพร่โฆษณาตามด้วยลำดับชั้นของหน่วยโฆษณา โดยคั่นด้วยเครื่องหมายทับ ตัวอย่างเช่น ข้อความนี้จะปรากฏโดยมีการจัดรูปแบบคล้ายกับ |
BidRequest.user.data[].segment[] |
BidRequest.adslot[].exchange_bidding.key_value[] |
คู่คีย์-ค่าซ้ำที่ส่งจากผู้เผยแพร่โฆษณาไปยังผู้เสนอราคาแลกเปลี่ยน คุณระบุได้ว่าค่าดังกล่าวเป็นคู่คีย์-ค่าที่ผู้เผยแพร่โฆษณาส่งเมื่อตั้งค่า |
ประกาศผู้ให้บริการที่ได้รับอนุญาต
ผู้ให้บริการเทคโนโลยีที่ให้บริการ เช่น การวิจัย รีมาร์เก็ตติ้ง และการแสดงโฆษณา อาจมีบทบาทในการโต้ตอบระหว่างผู้ซื้อกับผู้ขาย อนุญาตเฉพาะผู้ให้บริการที่ Google ได้ตรวจสอบแล้วสำหรับการเข้าร่วมการโต้ตอบของ Authorized Buyers
เพื่อทำความเข้าใจBidRequest
และสร้างBidResponse
คุณต้องตระหนักถึงความเป็นไปได้ 2 ประการในการประกาศผู้ให้บริการเทคโนโลยี ดังนี้
- ผู้ให้บริการบางรายไม่จำเป็นต้องได้รับแจ้ง ผู้ให้บริการเหล่านี้แสดงรายการอยู่ในศูนย์ช่วยเหลือของ Authorized Buyers
- ผู้ให้บริการรายอื่นๆ จะเข้าร่วมได้ต่อเมื่อมีการประกาศยืนยันทั้งใน
BidRequest
และBidResponse
ต่อไปนี้- ในช่อง
BidRequest
ช่องallowed_vendor_type
จะระบุผู้ให้บริการที่ผู้ขายอนุญาต ผู้ให้บริการที่จะส่งในช่องallowed_vendor_type
ของBidRequest
จะมีรายชื่ออยู่ในไฟล์พจนานุกรมVendors.txt
- ในช่อง
BidResponse
ช่องvendor_type
จะระบุผู้ให้บริการที่ได้รับอนุญาตที่ผู้ซื้อตั้งใจจะใช้
- ในช่อง
ตัวอย่างคำขอราคาเสนอ
ตัวอย่างต่อไปนี้แสดงตัวอย่างที่มนุษย์อ่านได้ของคำขอ Protobuf และ JSON
JSON ของ OpenRTB
โปรโตคอล OpenRTB
หากต้องการแปลงคำขอราคาเสนอเป็นรูปแบบไบนารีแบบที่คุณจะได้รับจากเพย์โหลด POST ในคำขอจริง ก็ทำดังต่อไปนี้ได้ (ใน C++) โปรดทราบว่าวิธีนี้ใช้ไม่ได้กับ OpenRTB JSON
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 } }
รีมาร์เก็ตติ้ง
Authorized Buyers ส่งรหัสโฆษณาบนอุปกรณ์เคลื่อนที่ในคำขอราคาเสนอจากแอปพลิเคชันบนอุปกรณ์เคลื่อนที่ รหัสโฆษณาบนอุปกรณ์เคลื่อนที่อาจเป็น
iOS IDFA หรือ
รหัสโฆษณาของ Android ซึ่งส่งผ่านมาโคร
%%EXTRA_TAG_DATA%%
ในแท็ก JavaScript ที่จัดการโดย Authorized Buyers
มาโคร %%ADVERTISING_IDENTIFIER%%
ช่วยให้ผู้ซื้อได้รับ iOS IDFA หรือรหัสโฆษณาของ Android ในการแสดงผล โดยแสดงผลบัฟเฟอร์ Proto ที่เข้ารหัส MobileAdvertisingId
เช่น
%%EXTRA_TAG_DATA%%
:
message MobileAdvertisingId { optional bytes advertising_id = 1; optional int32 user_id_type = 2; }
user_id_type
เป็นค่าหนึ่งที่กำหนดไว้ใน enum AdxMobileIdType
enum AdxMobileIdType { MOBILE_ID_UNKNOWN = 0, IDFA = 1, ANDROID_ID = 2, };
คุณสามารถสร้างรายชื่อผู้ใช้จากรหัสโฆษณาบนอุปกรณ์เคลื่อนที่โดยใช้รหัสโฆษณาที่คุณได้รวบรวมไว้ระหว่างการแสดงผล คุณสามารถดูแลรายการผู้ใช้เหล่านี้ บนเซิร์ฟเวอร์ของคุณหรือของเรา หากต้องการสร้างรายการผู้ใช้บนเซิร์ฟเวอร์ของ Google คุณสามารถใช้ บริการอัปโหลดจำนวนมากของเรา
เมื่อรหัสโฆษณาบนอุปกรณ์เคลื่อนที่ตรงกับรายการผู้ใช้ คุณจะใช้รหัสดังกล่าวเพื่อเรียกใช้รีมาร์เก็ตติ้งได้
ความคิดเห็นแบบเรียลไทม์
ความคิดเห็นแบบเรียลไทม์มีให้บริการแก่ Authorized Buyers รวมถึง Exchange และเครือข่ายที่ใช้การเสนอราคาแบบเปิด
ระบบรองรับความคิดเห็นการเสนอราคาตอบในคำขอราคาเสนอที่ตามมาสำหรับทั้งโปรโตคอล AdX และ OpenRTB สำหรับ OpenRTB ระบบจะส่งใน BidRequestExt
นอกจากช่องเริ่มต้นที่ส่งในส่วนความคิดเห็นการเสนอราคาตอบแล้ว คุณยังส่งข้อมูลที่กำหนดเองในการเสนอราคาตอบได้ (ทั้งใน AdX Proto หรือ OpenRTB) โดยใช้ event_notification_token
ที่แสดงผลใน BidResponse
event_notification_token
เป็นข้อมูลที่กําหนดเองซึ่งมีเฉพาะผู้เสนอราคาซึ่งอาจช่วยแก้ไขข้อบกพร่องได้ เช่น รหัสการกำหนดเป้าหมายหรือรหัสการเสนอราคาใหม่ที่แสดงถึงกลยุทธ์ใหม่ หรือข้อมูลเมตาที่เชื่อมโยงกับครีเอทีฟโฆษณาซึ่งผู้เสนอราคารู้จักเท่านั้น ดูรายละเอียด
ได้ที่บัฟเฟอร์โปรโตคอลส่วนขยายของ OpenRTB สำหรับ RTB และ AdX Proto
สำหรับ AdX
เมื่อ Authorized Buyers ส่งคำขอราคาเสนอไปยังผู้เสนอราคา ผู้เสนอราคาจะตอบกลับด้วย BidResponse
หากผู้เสนอราคาเปิดใช้ความคิดเห็นแบบเรียลไทม์ จากนั้นในคำขอราคาเสนอที่ตามมา Authorized Buyers จะส่งความคิดเห็นเกี่ยวกับการตอบกลับในข้อความ BidResponseFeedback
ดังที่แสดงด้านล่าง
// Feedback on bids submitted in previous responses. This is only set if // real-time feedback is enabled for your bidder. Contact your account // manager if you want to enable real-time feedback. 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; } repeated BidResponseFeedback bid_response_feedback = 44; // How many milliseconds Google will wait for a response before ignoring it. optional int32 response_deadline_ms = 57; // ----------------------------------------------------------- // Testing options. // // If true, then this is a test request. Results will not be displayed to // users and you will not be billed for a response even if it wins the // auction. You should still do regular processing since the request may be // used to evaluate latencies or for other testing. During your initial // testing with Google traffic any response that you make will be filtered // out of the auction whether this option has a value of true or false. optional bool is_test = 15 [default = false]; // If true, then this request is intended to measure network latency. // Return an empty BidResponse with only processing_time_ms set as quickly as // possible without executing any bidding logic. optional bool is_ping = 17 [default = false]; // If true, then the callout model predicted that you will not bid // on this request. We send a sampled percentage of such requests so that we // can automatically update the model when bidding patterns change. optional bool is_predicted_to_be_ignored = 45 [default = false]; // SupplyChain object. For more information, see // https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md. message SupplyChain { // Indicates whether the chain contains all nodes involved in the // transaction leading back to the owner of the site, app or other medium of // the inventory. optional bool complete = 1; message SupplyChainNode { // The canonical domain name of the SSP, Exchange, Header Wrapper, etc // system that bidders connect to. This may be the operational domain of // the system, if that is different than the parent corporate domain, to // facilitate WHOIS and reverse IP lookups to establish clear ownership of // the delegate system. This should be the same value as used to identify // sellers in an ads.txt file if one exists. optional string advertising_system_identifier = 1; // The identifier associated with the seller or reseller account within // the advertising system. This must contain the same value used in // transactions, specifically the publisher_id field in the Google // protocol. Should be limited to 64 characters in length. optional string seller_identifier = 2; // Indicates whether this node will be involved in the flow of payment for // the inventory. When set to true, the advertising system in the // advertising_system_identifier field pays the seller in the // seller_identifier field, who is responsible for paying the previous // node in the chain. When set to false, this node is not involved in the // flow of payment for the inventory. optional bool handles_payment = 6; } // Array of SupplyChainNode objects in the order of the chain. In a complete // supply chain, the first node represents the initial advertising system // and seller ID involved in the transaction, for example, the owner of the // site, app, or other medium. In an incomplete supply chain, it represents // the first known node. The last node represents the entity sending this // bid request. repeated SupplyChainNode nodes = 2; // Version of the supply chain specification in use, in the format of // "major.minor". For example, for version 1.0 of the spec, use the string // "1.0". optional string version = 3; } optional SupplyChain supply_chain = 69; // Experimental feature; may be subject to change. See // https://support.google.com/authorizedbuyers/answer/10890762 for more // information. // // Describes the scope of frequency cap enforcement available for this // request. Frequency caps to be enforced for a bid can be specified in the // BidResponse.ad.adslot.frequency_cap field. enum FrequencyCappingScope { // Default value which should not be used, or which can indicate that // frequency cap scope could not be reliably determined. FREQUENCY_CAPPING_SCOPE_UNKNOWN = 0; // Frequency capping based on bid response specifications is not available // for this request. A frequency-capped bid for a bid request with no // frequency cap availability will be filtered prior to the auction. FREQUENCY_CAPPING_SCOPE_NONE = 1; // Frequency capping enforcement is available across multiple sites within // the same browser. FREQUENCY_CAPPING_SCOPE_BROWSER = 2; // Frequency capping enforcement is available across multiple apps on the // device, excluding browsers. FREQUENCY_CAPPING_SCOPE_DEVICE = 3; // Frequency capping enforcement is available within a single app. FREQUENCY_CAPPING_SCOPE_APP = 4; // Frequency capping enforcement is available within a single site. FREQUENCY_CAPPING_SCOPE_SITE = 5; } optional FrequencyCappingScope frequency_capping_scope = 70; // The Digital Services Act (DSA) transparency requirements. See // https://support.google.com/admanager/answer/14335032. message Dsa { // Values indicating whether DSA declarations should be included in the bid // response and, if so, whether or not the publisher is an Online Platform // (OP) or Very Large Online Platform (VLOP), as defined by the DSA. enum DsaSupport { DSA_SUPPORT_UNKNOWN = 0; // DSA declarations are not required in the bid response. NOT_REQUIRED = 1; // DSA declarations are supported, but not required in the bid response. SUPPORTED = 2; // DSA declarations are required in the bid response. REQUIRED = 3; // DSA declarations are required in the bid response and the publisher is // an OP or VLOP. REQUIRED_BY_ONLINE_PLATFORM = 4; } // Indicates if DSA declarations should be included in the bid response. // Bids where DSA declarations are required but not included will not be // accepted. optional DsaSupport dsa_support = 1; // Options describing a publisher's ability to render DSA transparency // declarations. enum PublisherRenderingSupport { PUBLISHER_RENDERING_SUPPORT_UNKNOWN = 0; // Publisher can't render. PUBLISHER_UNABLE_TO_RENDER = 1; // Publisher could render depending on the buyer's rendering capability as // described in the BidResponse.ad.dsa_transparency.buyer_render field. PUBLISHER_CAN_RENDER = 2; // Publisher will render regardless of the buyer's rendering capability as // described in the BidResponse.ad.dsa_transparency.buyer_render field. PUBLISHER_WILL_RENDER = 3; } // Indicates if the publisher will render the DSA Transparency info. This // will signal if the publisher is able to and intends to render the icon // or other appropriate user-facing symbol and display the DSA transparency // info to the end user. optional PublisherRenderingSupport publisher_rendering_support = 2; // Options describing if a publisher requires DSA transparency declarations. enum DataToPublisher { DATA_TO_PUBLISHER_UNKNOWN = 0; // Do not send transparency data. DO_NOT_SEND = 1; // Optional to send transparency data. OPTIONAL = 2; // Send transparency data. SEND = 3; } // Indicates whether the bidder should provide DSA transparency declarations // in the bid response. A publisher may need this information for audit or // other purposes, even if they will not render the transparency // declarations themselves. optional DataToPublisher data_to_publisher = 3; } // The Digital Services Act (DSA) transparency information requirements. optional Dsa dsa = 86; } // This is the message that you return in response to a BidRequest. You may // specify zero or more ads. For each ad, you should provide an ad slot on // which the ad can run. An ad slot is identified by the AdSlot.id from the // BidRequest. If you do not want to bid, submit a response with no ads and // with only the processing_time_ms set. message BidResponse { message Ad { // The event notification token is sent to AdX by bidders for // troubleshooting. AdX will include the token in real-time feedback for the // bid. The content of the token will not be logged by AdX. AdX will ignore // any token longer than 128 bytes. optional bytes event_notification_token = 25; // A unique identifier chosen by you for the creative in this response. // This must always be set, must be limited to at most 64 bytes, and must be // a valid UTF8 string. Every buyer_creative_id you use must always be // associated with the same creative. This field is used to communicate // approval statuses when issues are found. Do not specify the same id for // different creatives, or all creatives will be disapproved if a problem // with a single creative is found. Do not specify different ids for the // same creative in different responses or no creatives will be served since // approval status is assigned on a per-id basis. optional string buyer_creative_id = 10; // Only one of the following should be set: // 1) html_snippet, 2) video_url, 3) native_ad, or 4) sdk_rendered_ad. // // The HTML snippet that will be placed on the web page to display the ad. // Use BidResponse.Ad.AdSlot.billing_id to indicate which billing id // this snippet is attributed to. optional string html_snippet = 1; // The URL to fetch a video ad. The URL should return an XML response that // conforms to the VAST 2.0 or 3.0 standard. Use // BidResponse.Ad.AdSlot.billing_id to indicate which billing id to // attribute this ad to. Only one of the following should be set: // html_snippet, video_url. Only set this field if the BidRequest is for an // in-video ad (BidRequest.video is present). optional string video_url = 9; // The VAST document to be returned. This document should conform to the // VAST 2.0 or 3.0 standard. Use BidResponse.Ad.AdSlot.billing_id to // indicate which billing ID to attribute this ad to. // Only set this field if the BidRequest is for an in-video ad and the // response is VAST XML. optional string video_vast_xml = 24; // The URL to fetch an AMPHTML ad. Only one of the following should be set: // html_snippet, video_url, amp_ad_url, native_ad. optional string amp_ad_url = 23; // The content of a native ad. Native ads consist of multiple building // blocks, which are rendered by the publisher. Only one of the following // should be set: html_snippet, video_url, or native_ad. // Only set this field if the BidRequest is for a native ad // (BidRequest.adslot.native is present). message NativeAd { // A video in the form of either a URL for a VAST tag, or an in-line VAST // tag. Only set this field if VIDEO is required or recommended in the // BidRequest's NativeAdTemplate. oneof video { // The URL to fetch a video ad. The URL should return an XML response // that conforms to VAST standards. string video_url = 13; // The VAST document to be returned. Max size is 100kB. string video_vast_xml = 16; } // A short title for the ad. optional string headline = 1; // A long description of the ad. optional string body = 2; // A label for the button that the user is supposed to click optional string call_to_action = 3; // The name of the advertiser or sponsor, to be displayed in the ad // creative. optional string advertiser = 4; message Image { optional string url = 1; // Image width and height are specified in pixels. You may provide a // larger image than was requested, so long as the aspect ratio is // preserved. optional int32 width = 2; optional int32 height = 3; } // A large image. optional Image image = 5; // A smaller image, for the advertiser's logo. optional Image logo = 6; // The app icon, for app download ads. optional Image app_icon = 7; // The app rating in the app store. Must be in the range [0-5]. optional double star_rating = 8; // The URL that the browser/SDK will load when the user clicks the ad. // This can be the landing page directly, or the first step of a redirect // chain that eventually leads to it. For backward compatibility, if this // is not set, the first Ad.click_through_url is used. optional string click_link_url = 14; // This field is deprecated in favor of the repeated click_tracking_urls // field at the BidResponse.Ad level. It will be removed at the end of // Q2 2022. // The URL to use for click tracking. The SDK pings click tracking url on // a background thread. When resolving the url, HTTP 30x redirects are // followed. The SDK ignores the contents of the response; this URL // has no effect on the landing page for the user. optional string DEPRECATED_click_tracking_url = 11 [deprecated = true]; // This field is deprecated in favor of the click_tracking_urls // field at the BidResponse.Ad level. It will be removed at the end of // Q2 2022. // The URLs to use for click tracking. This will be used throughout the // serving stack and will incorporate any URL in click_tracking_url. repeated string DEPRECATED_click_tracking_urls = 15 [deprecated = true]; // The price of the promoted app including the currency info. optional string price = 10; } optional NativeAd native_ad = 18; // The set of destination URLs for the snippet. This includes the URLs that // the user will go to if they click on the displayed ad, and any URLs that // are visible in the rendered ad. Do not include intermediate calls to the // adserver that are unrelated to the inal landing page. A BidResponse that // returns a snippet or video ad but declares no click_through_url will be // discarded. Only set this field if html_snippet or video_url or native_ad // are set. This data is used as a destination URL declaration, for example // for post-filtering of publisher-blocked URLs or ad categorization. // // For non-native ads, it is not used for click tracking or any // other ad functionality; it is only used as a destination URL // declaration. // // For native ads, if NativeAd.click_link_url is not set, the first // value of click_through_url is used to direct the user to the landing // page. In addition, all values are used as destination // URL declarations (similar to the non-native case). repeated string click_through_url = 4; // All vendor types for the ads that may be shown from this snippet. You // should only declare vendor ids listed in the vendors.txt file in the // technical documentation. We will check to ensure that the vendors you // declare are in the allowed_vendor_type list sent in the BidRequest for // AdX publishers. repeated int32 vendor_type = 5; // All attributes for the ads that may be shown from this snippet. See // buyer-declarable-creative-attributes.txt in the technical documentation // for a list of ids. We will check to ensure none of these attributes are // in the excluded_attribute list in the BidRequest. repeated int32 attribute = 6; // All sensitive categories for the ads that may be shown from this snippet. // See ad-sensitive-categories.txt in the technical documentation for a list // of ids. We will check to ensure none of these categories were in the // excluded_sensitive_category list in the BidRequest. repeated int32 category = 7; // All restricted categories for the ads that may be shown from this // snippet. See ad-restricted-categories.txt in the technical documentation // for a list of ids. We will check to ensure these categories were listed // in the allowed_restricted_category list in the BidRequest. If you are // bidding with ads in restricted categories you MUST ALWAYS declare them // here. repeated int32 restricted_category = 17; // All names of the ad's advertisers. repeated string advertiser_name = 11; // The width and the height in pixels of the ad. Setting these is optional. // However, these must be set if the bid BidRequest.AdSlot has more than one // width and height or if BidRequest.Mobile.is_interstitial_request is true. optional int32 width = 14; optional int32 height = 15; message AdSlot { // The slot id from the BidRequest that the ad may appear in. required int32 id = 1; // The maximum CPM you want to be charged if you win the auction for this // ad slot, expressed in micros of the specified currency or default // bidding currency. For example, to bid a CPM of 1.29 USD, set // max_cpm_micros = 1290000. Winning bids are rounded up to billable // units. For example, in USD, bids are rounded up to the next multiple // of 10,000 micros (one cent). required int64 max_cpm_micros = 2; // The minimum CPM you want to be charged if you win the auction for this // ad slot, expressed in micros of the specified currency or default // bidding currency. This may represent a second price if you choose // max_cpm_micros as the highest of several bids, or some form of reserve // price if you want to override the reserve price set by the publisher. // The bid must be less than or equal to max_cpm_micros or it will be // ignored. This field is optional and does not need to be set. This // field is not applicable when responding to bid requests with // auction_type set to FIRST_PRICE. optional int64 min_cpm_micros = 3; // The currency used by max_cpm_micros and min_cpm_micros, using ISO-4217 // alpha codes. If this field is populated, the specified currency will // be used to interpret the bid. Otherwise, the default bidding currency // will be used, which is determined in the following priority: // 1. The bidder-level currency, if configured in RTB account settings. // 2. The buyer-level currency. The buyer will be determined by the // billing ID specified in the billing_id field of the bid response if it // is populated, otherwise it will be based on the sole billing ID sent // in the bid request. // // The currency of a buyer account is set on account creation and can be // checked by contacting a Technical Account Manager. optional string currency = 15; // Billing id to attribute this impression to. The value must be in the // set of billing ids for this slot that were sent in the // BidRequest.AdSlot.matching_ad_data.billing_id. This must always be set // if the BidRequest has more than one // BidRequest.AdSlot.matching_ad_data.billing_id or if the bidder has // active child seats. optional int64 billing_id = 4; // The deal id that you want this bid to participate in. Leave unset // or set it to "1" if a deal is available but you want to // ignore the deal and participate in the open auction. optional int64 deal_id = 5 [default = 0]; // For exchange bidders (third party exchanges doing real-time bidding on // DFP), the deal id from the exchange's namespace that is associated with // this bid and reported to publishers. Leave unset if there is no // associated deal. This is arbitrary UTF8 text and must be at most 64 // bytes. optional string exchange_deal_id = 6; // When exchange_deal_id is set, the type of deal. This is reported to // publishers and affects how the deal is treated in the auction. enum ExchangeDealType { OPEN_AUCTION = 0; PRIVATE_AUCTION = 1; PREFERRED_DEAL = 2; EXCHANGE_AUCTION_PACKAGE = 3; } optional ExchangeDealType exchange_deal_type = 7 [default = OPEN_AUCTION]; // The seat ID in the bidder's namespace representing the seat on whose // behalf this bid was made. optional string seat_id = 25; // Buyer declared ID which will be used to break down spend and invalid // traffic metrics in IVT transparency reporting in Query Tool. Note that // IDs with fewer than 1000 impressions will not be used to break down // metrics. IDs longer than 64 bytes will be ignored. optional string buyer_reporting_id = 8; // Token used to identify end third party buyer information if an // exchange as an open bidder is an intermediary. This is obtained from // the third party buyer and must be passed to Google unaltered in the bid // response. optional string third_party_buyer_token = 12; // Experimental feature; may be subject to change. See // https://support.google.com/authorizedbuyers/answer/10890762 for more // information. // // Specifies frequency capping to be applied to the bid. Impressions for // each user are capped at the level specified by frequency_cap_id. A bid // will not participate in the auction if an additional impression for the // user would violate any of the specified caps. Multiple frequency caps // can be specified for the same frequency_cap_id. // // A bid is filtered before the auction if the frequency cap is malformed. // Instances where the cap is malformed include: // - frequency_cap_id is empty or is very long // - max_mpressions or time_range are non-positive // - there are a large number of frequency caps for a single bid // - time_unit is not specified // // Note that if a subsequent bid with the same frequency_cap_id uses a // different duration (represented by time_unit and time_range) then // impressions counted against the old frequency cap will not count // against the new one, and the impressions counted against the new // frequency cap with a different time_unit and time_range will not count // against the old frequency cap.. message FrequencyCap { // An ID that can represent a bidder's use-case for frequency capping. // For example, it could represent their campaign, ad, line item, or // some other entity. It should not contain any user-specific // information or identifiers and should not be longer than 64 // characters. optional string frequency_cap_id = 1; // The time units for which frequency caps can be enforced. enum TimeUnit { UNKNOWN_TIME_UNIT = 0; MINUTE = 1; DAY = 2; WEEK = 3; MONTH = 4; // When INDEFINITE is used, time_range will be ignored. INDEFINITE // means the frequency cap will be applied for a long period of time, // (longer than a month) but not necessarily forever. INDEFINITE = 5; } // The unit of time used to specify the time window for which a // frequency cap applies. optional TimeUnit time_unit = 2; // The length of the time window, in units specified by time_unit, for // which the frequency cap applies. For instance, if time_unit=WEEK and // time_range=3, then capping is applied for a three week period. If the // time_unit=INDEFINITE, this will be ignored. optional int32 time_range = 3 [default = 1]; // The maximum number of impressions allowed to be shown to a user for // the provided frequency_cap_id within the time window described by // time_unit and time_range. optional int32 max_impressions = 4; } repeated FrequencyCap frequency_cap = 16; // Position within the pod. enum PodPosition { // Any position in the pod. POD_POSITION_ANY = 0; // Last position in the pod. POD_POSITION_LAST = 1; // First position in the pod. POD_POSITION_FIRST = 2; // First or last position in the pod. POD_POSITION_FIRST_OR_LAST = 3; } // Indicates that the bid is only eligible // for a specific position within the pod. optional PodPosition position_in_pod = 22; // All bids with the same bid_group_id will be won or lost as a group. // Bids must have a non-empty bid_group_id to allow an ad to be played // as part of a pod. // This field is currently only supported for rewarded video pods // requests. If an ad is submitted on multiple positional bids // represented by AdSlot messages, each bid (AdSlot message) // must have a different bid_group_id. // For example, if a bidder wants to bid ad_1 for first position // and last position in the pod and ad_2 for any position and // want to ensure either both win at the same time or neither of those // wins, bidder needs to submit: // ad { // buyer_creative_id: "ad_1", // adslot { // position_in_pod: POD_POSITION_FIRST, // bid_group_id: "group1" // }, // adslot { // position_in_pod: POD_POSITION_LAST, // bid_group_id: "group2" // } // }, // ad { // buyer_creative_id: "ad_2", // adslot { // position_in_pod: POD_POSITION_ANY, // bid_group_id: "group1" // }, // adslot { // position_in_pod: POD_POSITION_ANY, // bid_group_id: "group2" // } // } optional string bid_group_id = 23; } repeated AdSlot adslot = 3; // The URLs to call when the impression is rendered. This is supported for // all inventory types and all formats. repeated string impression_tracking_url = 19; // The URLs to call when the user clicks on the ad. Currently supported only // for native ads and Programmatic Guaranteed deals with publisher- // managed creatives. In the publisher managed case, these click trackers // will be sent to the bidder server to server. In all other cases, these // will be sent from the user's device. For more information on // publisher-managed creatives, see // https://support.google.com/admanager/answer/9243220. repeated string click_tracking_urls = 30; // Link to ad preferences page. This is only supported for native ads. // If present, a standard AdChoices icon is added to the native creative and // linked to this URL. optional string ad_choices_destination_url = 21; message ImpressionTrackingResource { // The URL of a Javascript resource. The URLs should not contain script // tags. For example: "https://mycdn.com/tracker.js". optional string script_url = 1; // Additional context provided for rendering. enum Context { UNKNOWN_CONTEXT = 0; // Currently not supported. OMID = 1; } repeated Context context = 2; // Parameters associated with the resource that will be passed to the // resource when it is loaded. The format of the parameters is dependent // on the script vendor. optional string verification_parameters = 3; // Used to uniquely identify the verification script provider. optional string vendor_key = 4; } // Resources to invoke when the impression is rendered. This is supported // for native and banner formats only and explicitly allowed scripts // only. repeated ImpressionTrackingResource impression_tracking_resource = 26; // An ad that will be rendered by an SDK known to the buyer. This can only // be used when the BidRequest included a mobile.installed_sdk submessage. message SdkRenderedAd { // The identifier for the SDK that will render the ad. Must match a // mobile.installed_sdk.id sent in the corresponding bid request. optional string id = 1; // Data to pass to the SDK in order to render the ad. This data is opaque // to the publisher and to Google. optional string rendering_data = 2; // Declared ad assets to support creative scanning, classification, and // enforcement of ad policy and publisher blocks for ads rendered with a // custom SDK. message DeclaredAd { // Ad content used by SDK to render an ad. oneof content { // The HTML snippet representative of the SDK-rendered ad. string html_snippet = 1; // The URL to the VAST asset used in the SDK-rendered ad. string video_url = 2; // The VAST document used to render custom SDK-rendered ad. This // document should conform to the VAST 2.0 or 3.0 standard. string video_vast_xml = 5; // The content of a native ad. Native ads consist of multiple building // blocks (such as image and text), which are rendered by the buyer // SDK. NativeAd native_ad = 6; } // The final landing pages of the SDK-rendered ad. repeated string click_through_url = 4; } optional DeclaredAd declared_ad = 6; } optional SdkRenderedAd sdk_rendered_ad = 27; // Advertiser's SKAdNetwork information to support app installation // attribution for iOS 14 and later. Apple's SKAdNetwork API helps // advertisers measure ad-driven app installation by sending a postback // to the ad network after a successful install. Ad networks will need // to send their network ID and signed advertiser information to allow // an install to be attributed to the ad impression. // For more info visit: // https://developer.apple.com/documentation/storekit/skadnetwork message SKAdNetworkResponse { // Version of SKAdNetwork supported by the advertiser. Also used to // specify how the signature was generated by the advertiser. This // should match the version from BidRequest.mobile.skad.version. optional string version = 1; // Ad network identifier used in signature. This should match one of the // items in BidRequest.mobile.skad.skadnetids. optional string network = 2; // Campaign ID compatible with Apple's spec. Used in SKAdNetwork 3.0 and // below. Replaced by Source Identifier (`source_identifier` field) in // SKAdNetwork 4.0 and above. optional int64 campaign = 3; // A four-digit integer that ad networks define to represent the ad // campaign. Used in SKAdNetwork 4.0+ and replaces the `campaign` field. optional int64 source_identifier = 11; // ID of advertiser's app in Apple's app store. optional string itunesitem = 4; // ID of custom product page to display (for iOS 15 or later). // If not specified, default product page will be displayed. // See https://developer.apple.com/app-store/custom-product-pages/ // for more details about custom product pages. optional string product_page_id = 12; // SKAdNetwork API starting from version 2.2 supports multiple ad // presentation options specified by the `fidelity-type` parameter of the // SKAdNetwork signature. This holds parameters used to generate the // signature that would be different for each fidelity type supported. // For more info visit: // https://developer.apple.com/documentation/storekit/skadnetwork/signing_and_providing_ads message Fidelity { // The fidelity type of the attribution to track. optional SKAdNetworkFidelityType fidelity_type = 1 [default = STOREKIT_RENDERED_ADS]; // A unique all-lowercase UUID generated by the advertiser to use for // generating the signature. optional string nonce = 2; // Unix time in millis used at the time of signature generation. optional int64 timestamp = 3; // SKAdNetwork signature as specified by Apple. optional string signature = 4; } repeated Fidelity fidelities = 9; // A unique all-lowercase UUID generated by the advertiser to use for // generating the signature. // Note: This field will be deprecated in favor of the // BidResponse.ad.skadn.fidelities.nonce field to support multiple // fidelity types. optional string nonce = 5; // ID of publisher's app in Apple's app store. This should match the ID // from BidRequest.mobile.skad.sourceapp. optional string sourceapp = 6; // Unix time in millis used at the time of signature generation. // Note: This field will be deprecated in favor of the // BidResponse.ad.skadn.fidelities.timestamp field to support multiple // fidelity types. optional int64 timestamp = 7; // SKAdNetwork signature as specified by Apple. // Note: This field will be deprecated in favor of the // BidResponse.ad.skadn.fidelities.signature field to support multiple // fidelity types. optional string signature = 8; // These options indicate how to present SKOverlay recommending the // advertised app. // Supported by iOS 14 and later. // // For more info visit: // https://developer.apple.com/documentation/storekit/skoverlay message SKOverlay { // Delay in seconds after the ad begins before presenting the overlay. // If this field is set to 0, the overlay will be shown immediately // after the ad begins. If this field is unset, the overlay will not // be shown for the ad. optional int32 delay_seconds = 1; // Delay in seconds after the endcard shows before presenting the // overlay. (This field only applies to rewarded or interstitial video // creatives.) If this field is set to 0, the overlay will be shown // immediately after the endcard shows. If this field is unset, // the overlay will not be shown for the endcard. // If both `delay_seconds` and `endcard_delay_seconds` are set, // the overlay will be automatically dismissed when the ad ends, // and shown again after the endcard shows. optional int32 endcard_delay_seconds = 2; // Whether this overlay can be dismissed by the user. optional bool dismissible = 3 [default = true]; } optional SKOverlay skoverlay = 13; // Google Mobile Ads SDK options for SKAdNetwork handling. message SKAdNetworkOptions { // By default, SKAdNetwork attribution will only be initiated if the // click-through URL lands on the app store, either as a direct link to // the app store or as the final destination of a server-side redirect // chain. Enables GMA SDK to always initiate SKAdNetwork // attribution on-click regardless of the detected click's final // destination URL. Note that enabling this will launch the app store // even for clicks that are not meant to open the app store, for example // clicks on Ad Choices icon. For more info, see: // https://developers.google.com/authorized-buyers/rtb/skadnetwork optional bool always_open_appstore = 1 [default = false]; } optional SKAdNetworkOptions skadn_options = 10; } optional SKAdNetworkResponse skadn = 29; // ID of the advertised app (only for app promotion). // On Android, this should be a bundle or package name such as // com.foo.mygame. On iOS, it is a numeric ID. // // In addition to this field, set the app_promotion_type field below to take // advantage of features specific to app promotion types. optional string advertised_app_id = 32; // Possible types of app promotion. enum AppPromotionType { UNKNOWN_APP_PROMOTION_TYPE = 0; // For encouraging new users to download and install the advertised app. // Clicking this ad will show the app store listing as an overlay (for // supported formats), without leaving the publisher app. // Click through URL for this ad points to the app store listing. INSTALLS = 1; // Other types of app promotion that do not fall into the categories // above. No features specific to app promotion types will apply. OTHER = 3; } // Type of the app promotion corresponding to the advertised app specified // in the advertised_app_id field above. // If the advertised app is not specified, this field will be ignored. // // Setting advertised_app_id field without this field will be treated as if // this field were set to OTHER. optional AppPromotionType app_promotion_type = 33; // DSA Ad Transparency declarations. See // https://support.google.com/admanager/answer/14335032. message DsaTransparency { // Free text string describing the name of the advertiser on whose behalf // the ad is shown. Bids will not be accepted if this value is longer // than 100 characters. optional string displayed_on_behalf = 1; // Free text string describing the advertiser who paid for the ad. Must // always be included even if it's the same as what is listed in the // displayed_on_behalf attribute. Bids will not be accepted if this value // is longer than 100 characters. optional string paying_entity = 2; // Indicates that the buyer will render their own DSA transparency // information inside the creative. optional bool buyer_render = 3; } // DSA Ad Transparency information provided by the buyer. optional DsaTransparency dsa_transparency = 39; } repeated Ad ad = 2; // If is_test was set in the BidRequest, then you may return debug information // as plain text in this field. Don't set this field under normal // conditions, or set it to values longer than 100 characters. You should only // use this field when asked to do so as part of troubleshooting particular // problems. optional string debug_string = 5; // Set this to the processing time in milliseconds from when you // received the request to when you returned the response. optional int32 processing_time_ms = 4; // An optional, bidder-specified reason for not submitting a bid. This field // is equivalent to BidResponse.nbr in the OpenRTB protocol and uses the same // namespace of no-bid reason codes. See // https://developers.google.com/authorized-buyers/rtb/downloads/no-bid-reasons.txt // for the full set of no-bid reason codes. optional int32 no_bid_reason = 6; } // SKAdNetwork API starting from version 2.2 supports multiple ad // presentation options specified by the `fidelity-type` parameter of the // SKAdNetwork signature. The following are the fidelity types supported by // Apple. For more info visit: // https://developer.apple.com/documentation/storekit/skadnetwork/signing_and_providing_ads enum SKAdNetworkFidelityType { // Attribution for app installs within 24 hours of viewing an ad for at least // 3 seconds. Supported for SKAdnetwork version 2.2 and up. For more info see: // https://developer.apple.com/documentation/storekit/skadnetwork/generating_the_signature_to_validate_view-through_ads VIEW_THROUGH_ADS = 0; // Attribution for app installs initiated from the StoreKit-rendered App Store // product page driven by ad clicks. Supported for all SKAdNetwork versions. // For more info see: // https://developer.apple.com/documentation/storekit/skadnetwork/generating_the_signature_to_validate_storekit-rendered_ads STOREKIT_RENDERED_ADS = 1; }
จากข้อความนี้ ช่องแรกที่ควรตรวจสอบคือ bid_response_feedback.creative_status_code
คุณจะเห็นโค้ดที่สื่อความหมายใน
creative-status-codes.txt โปรดทราบว่าหากคุณชนะการประมูล คุณสามารถเลือกไม่รับความคิดเห็นเกี่ยวกับราคาได้ ดูข้อมูลเพิ่มเติมได้ที่วิธีเลือกไม่ใช้
ความคิดเห็นแบบเรียลไทม์จะมีรหัสคำขอราคาเสนอและ
ผลการประมูล | ความคิดเห็นแบบเรียลไทม์ |
---|---|
ผู้ซื้อไม่ได้ส่งราคาเสนอ | ไม่มี |
ผู้ซื้อส่งราคาเสนอที่ถูกกรองออกไปก่อนที่จะเข้าสู่การประมูล | รหัสสถานะครีเอทีฟโฆษณา (creative-status-codes.txt) |
ผู้ซื้อส่งราคาเสนอแล้วแต่แพ้การประมูล | รหัสสถานะครีเอทีฟโฆษณา 79 (มีผู้เสนอราคาสูงกว่าในการประมูล) |
ผู้ซื้อส่งราคาเสนอที่ชนะการประมูล | รหัสราคาและรหัสสถานะครีเอทีฟโฆษณาที่ล้างออก 1
สำหรับการแสดงผลแอปและรหัสสถานะครีเอทีฟโฆษณา |
ตัวอย่าง
ต่อไปนี้คือตัวอย่างของความคิดเห็นแบบเรียลไทม์ที่เห็นในโปรโตคอลที่รองรับ
JSON ของ OpenRTB
โปรโตคอล OpenRTB
สร้างโมเดลการเสนอราคาสำหรับการประมูลแบบใช้ราคาอันดับ 1
หลังจากใส่ราคาเสนอในการประมูลแบบใช้ราคาอันดับ 1 แล้ว คุณจะได้รับความคิดเห็นแบบเรียลไทม์ รวมถึงช่อง minimum_bid_to_win
และ sampled_mediation_cpm_ahead_of_auction_winner
หากราคาเสนอไม่ได้ถูกกรองออกจากการประมูล สัญญาณเหล่านี้สามารถใช้เพื่อแจ้งตรรกะการเสนอราคาของคุณว่าราคาเสนอจะสูงหรือต่ำลงมากน้อยเพียงใดเพื่อที่จะชนะการแสดงผล
minimum_bid_to_win
: ราคาเสนอขั้นต่ำที่สามารถชนะการประมูลเสนอราคาแบบเรียลไทม์ได้ หากคุณชนะการประมูล นี่จะเป็นราคาเสนอต่ำสุดเท่าที่คุณสามารถเสนอได้ขณะที่ยังคงชนะการประมูล หากคุณแพ้การประมูล นี่จะเป็นราคาเสนอที่ชนะsampled_mediation_cpm_ahead_of_auction_winner
: หากมีเครือข่ายอื่นๆ ในห่วงโซ่สื่อกลาง ค่าของช่องนี้คือราคาที่แสดงราคาเสนอตัวอย่างจากเครือข่ายสื่อกลางที่มีสิทธิ์เครือข่ายใดเครือข่ายหนึ่งที่สูงกว่าผู้ชนะการประมูล ซึ่งถ่วงน้ำหนักด้วยอัตราการส่งโฆษณาที่คาดไว้ ค่านี้จะตั้งเป็น 0 หากไม่มีเครือข่ายในห่วงโซ่สื่อกลางใดที่คาดว่าจะมีการส่งโฆษณา หรือหากผู้เผยแพร่โฆษณาไม่ได้ใช้สื่อกลาง SDK
วิธีการทำงาน
เพื่ออธิบายการคำนวณที่ใช้ระบุค่าที่เป็นไปได้สำหรับ minimum_bid_to_win
และ sampled_mediation_cpm_ahead_of_auction_winner
ก่อนอื่นเราต้องกำหนดค่าต่อไปนี้
- ค่าต่อไปนี้แสดง CPM ในเชนสื่อกลางตามลำดับขั้นจากมากไปน้อย
\[C_1, C_2, …, C_n\]
- ค่าต่อไปนี้แสดงอัตราการส่งโฆษณาที่เกี่ยวข้องสำหรับ CPM ในห่วงโซ่สื่อกลาง
\[f_1, f_2, …, f_n\]
- ฟังก์ชันต่อไปนี้คือฟังก์ชันที่ใช้กำหนด CPM ที่คาดหวังและความน่าจะเป็นจากองค์ประกอบเชนสื่อกลาง \(i\)โดยอิงตามอัตราการส่งโฆษณาที่ระบุ
\(X_i = \{C_i\) กับความน่าจะเป็น \(f_i\)\(0\) ที่มีความน่าจะเป็น \(1 - f_i\}\)
- เชนสื่อกลางที่ชนะในขั้นสุดท้ายคือ
\[\{C_1, C_2, …, C_K, W\}\]โดยที่ \(W\) เป็นราคาเสนอที่ชนะ และ \(C_K > W >= C_{K+1}\)
- ราคาจองหรือราคาพื้นจะระบุเป็น \(F\)
- ราคาเสนอรองจะแสดงเป็น \(R\)
การคำนวณสำหรับผู้ชนะการประมูล
ฟิลด์ | การคำนวณ |
---|---|
minimum_bid_to_win |
\(max\{F, R, X_{K+1}, …, X_n\}\) |
sampled_mediation_cpm_ahead_ |
\(\{C_i\) ที่มีความน่าจะเป็น \(\prod_{j=1}^{i-1}(1-f_j) \cdot f_i \div \prod_{j=1}^{K}(1-f_j)\}\)
สำหรับ \(1 <= i <= K\) |
การคำนวณสำหรับผู้ที่แพ้การประมูล
ฟิลด์ | การคำนวณ |
---|---|
minimum_bid_to_win |
\(max\{F, W\}\) |
sampled_mediation_cpm_ahead_ |
\(max\{X_1, …, X_K\}\) |
ตัวอย่างด้วยเชนสื่อกลางที่เรียบง่าย
สมมติว่าผู้เผยแพร่โฆษณาใช้ทั้งการเสนอราคาแบบเรียลไทม์และเชนสื่อกลาง SDK ดังนี้
เชนสื่อกลาง SDK | CPM ที่คาดหวัง | อัตราการส่งโฆษณา |
---|---|---|
เครือข่าย 1 | \(C_1 = $3.00\) | \(f_1 = 5\%\) |
เครือข่าย 2 | \(C_2 = $2.00\) | \(f_2 = 45\%\) |
เครือข่าย 3 | \(C_3 = $0.50\) | \(f_3 = 80\%\) |
เครือข่าย 4 | \(C_4 = $0.10\) | \(f_4 = 85\%\) |
สมมติว่าสิ่งต่อไปนี้เป็นผลมาจากการประมูล RTB
การประมูล RTB | CPM |
---|---|
ผู้ชนะการประมูล (W) | 30.00 บาท |
ผู้ชนะการประมูล (R) | 10.50 บาท |
ราคาจอง / ชั้น (F) | $0 |
ราคาเสนอที่ชนะการประมูล
ต่อไปนี้เป็นตัวอย่างวิธีการคำนวณมูลค่าและความน่าจะเป็นสำหรับ minimum_bid_to_win
และ sampled_mediation_cpm_ahead_of_auction_winner
สำหรับราคาเสนอที่ชนะ
minimum_bid_to_win |
Probability |
---|---|
\(max(F, R, C_3) = $0.50\) | \(f_3 = 80\%\) |
\(max(F, R, C_4) = $0.10\) | \((1-f_3) \cdot f_4 = 17\%\) |
\(max(F, R, 0) = $0.05\) | \((1-f_3) \cdot (1-f_4) = 3\%\) |
sampled_mediation_cpm_ |
Probability |
---|---|
\(C_1 = $3.00\) | \(f_1 \div (1-(1-f_1) \cdot (1-f_2)) =~ 10.5\%\) |
\(C_2 = $2.00\) | \(((1-f_1) \cdot f_2) \div (1-(1-f_1) \cdot (1-f_2)) =~ 89.5\%\) |
ราคาเสนอที่แพ้การประมูล
ต่อไปนี้เป็นตัวอย่างวิธีการคำนวณมูลค่าและความน่าจะเป็นสำหรับ minimum_bid_to_win
และ sampled_mediation_cpm_ahead_of_auction_winner
สำหรับราคาเสนอที่แพ้
minimum_bid_to_win |
Probability |
---|---|
\(max(F, W) = $1.00\) | \(100\%\) |
sampled_mediation_cpm_ |
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\%\) |
การแยกการเสนอราคา
การแยกการเสนอราคาอธิบายการประมวลผล BidRequest
ที่ซับซ้อนรายการเดียวลงในคำขอราคาเสนอหลายรายการที่ส่งไปยังแอปพลิเคชันของคุณ เนื่องจากยังคงมีรหัสที่เหมือนกัน
(BidRequest.google_query_id
ในโปรโตคอล RTB ของ Authorized Buyers
หรือ BidRequestExt.google_query_id
ในโปรโตคอล OpenRTB) คุณจึงสามารถ
กำหนดได้ว่าคำขอราคาเสนอใดมีความสัมพันธ์กันหลังจากการแยก
รูปแบบโฆษณา
โอกาสในการโฆษณาบางรูปแบบสามารถยอมรับได้หลายรูปแบบ เมื่อใช้การแยกการเสนอราคา ระบบจะส่งแต่ละรูปแบบไปในคำขอราคาเสนอที่แตกต่างกัน โดยที่แอตทริบิวต์ต่างๆ เช่น รหัสการเรียกเก็บเงินที่มีสิทธิ์ จะเกี่ยวข้องกับรูปแบบที่ระบุไว้ในคำขอ
คำขอราคาเสนอที่มีรูปแบบต่อไปนี้จะถูกแยกออกเป็นคำขอราคาเสนอที่แตกต่างกัน
- แบนเนอร์
- วิดีโอ
- เสียง
- เนทีฟ
ตัวอย่างการแยกรูปแบบโฆษณา
ด้านล่างคือตัวอย่างที่แสดงคำขอราคาเสนอ OpenRTB JSON แบบง่ายที่ไม่มีการแยกรูปแบบโฆษณาเมื่อเทียบกับชุดคำขอที่แยกเป็นหลายรายการที่เทียบเท่ากัน
แบบเรียบ
หลังผ้าแบน
ดีล
โอกาสในการโฆษณาสำหรับผู้เสนอราคาหนึ่งๆ สามารถใช้ได้กับดีลประเภทต่างๆ นอกเหนือจากการประมูลแบบเปิด เมื่อมีการแยกราคาเสนอสำหรับดีล จะมีการส่งคำขอราคาเสนอ 1 รายการสำหรับการประมูลแบบเปิด และอีกคำขอหนึ่งสำหรับดีลราคาคงที่แต่ละประเภท ในทางปฏิบัติ ข้อจำกัดโฆษณาอาจแตกต่างกันระหว่างการประมูลกับดีลประเภทราคาคงที่ เช่น สำหรับโอกาสโฆษณาวิดีโอหนึ่งๆ ซึ่งใช้ได้กับทั้งการประมูลแบบเปิดและดีลราคาคงที่ ผู้เสนอราคาจะได้รับคำขอราคาเสนอที่แตกต่างกันสำหรับแต่ละข้อจำกัด เช่น ระยะเวลาสูงสุดของโฆษณา และอนุญาตให้ใช้โฆษณาแบบข้ามได้ที่แตกต่างกันหรือไม่ ด้วยเหตุนี้ การแยกโฆษณาจึงช่วยให้คุณแยกแยะข้อจำกัดของโฆษณาสำหรับการประมูลแบบเปิดและดีลราคาคงที่ได้ง่ายขึ้น
ระยะเวลาสูงสุดของวิดีโอที่ข้ามได้
โปรโตคอลของ Google และการใช้งาน OpenRTB รองรับช่องต่อไปนี้สำหรับระยะเวลาของวิดีโอและความสามารถในการกดข้ามได้
ระยะเวลา | ระยะเวลาที่ข้ามได้ | ความสามารถในการข้าม | |
---|---|---|---|
โปรโตคอลของ Google | max_ad_duration |
skippable_max_ad_duration |
video_ad_skippable |
OpenRTB | maxduration |
ไม่มี | skip |
ซึ่งหมายความว่าในขณะที่โปรโตคอลของ Google สามารถมีระยะเวลาแบบข้ามได้และข้ามไม่ได้แบบละเอียด แต่การใช้งาน OpenRTB จะมีค่าระยะเวลาสูงสุดเพียงค่าเดียวเท่านั้น
โดยก่อนที่จะแยกการเสนอราคา ระบบจะตั้งค่า maxduration
ของ OpenRTB ให้อยู่ต่ำกว่าช่อง max_ad_duration
และ skippable_max_ad_duration
ของโปรโตคอล Google ตอนนี้ลักษณะการทำงานนี้ได้เปลี่ยนไปเป็นการส่งคำขอราคาเสนอ 2 รายการแยกกันเมื่อค่าเหล่านี้แตกต่างกัน โดยค่าหนึ่งแสดงถึง maxduration
สำหรับโฆษณาแบบข้ามได้และอีกค่าหนึ่งสำหรับโอกาสแบบข้ามไม่ได้
ตัวอย่างต่อไปนี้แสดงให้เห็นว่าคำขอโปรโตคอลของ Google แปลงเป็น OpenRTB ก่อนและหลังการแยกการเสนอราคา คำขอโปรโตคอลของ Google ที่เทียบเท่ามี max_ad_duration
เป็น 15
และ skippable_max_ad_duration
เป็น 60
ตัวอย่าง | max_ad_duration |
skip (จริงหรือเท็จ) |
---|---|---|
คำขอเดิมที่ไม่มีการแยก | 15 |
true |
คำขอที่แยกเป็นหลายรายการ #1: ข้ามไม่ได้ | 15 |
false |
คำขอที่แยกเป็นหลายรายการ #2: ข้ามได้ | 60 |
true |
การแยกคำขอราคาเสนอสำหรับระยะเวลาของวิดีโอที่ข้ามได้จะเกิดขึ้นก็ต่อเมื่อเป็นไปตามเงื่อนไขต่อไปนี้เท่านั้น
- คำขอนี้อนุญาตให้มีวิดีโอ
- อนุญาตให้ใช้ทั้งวิดีโอที่ข้ามได้และข้ามไม่ได้ และระยะเวลาสูงสุดทั้งสองนี้จะมีมูลค่าแตกต่างกัน
- คำขอนี้มีสิทธิ์สำหรับการประมูลส่วนตัวหรือการประมูลแบบเปิด
- บัญชีผู้เสนอราคามีปลายทาง OpenRTB ที่ใช้งานอยู่
คุณเลือกไม่ใช้การแยกประเภทนี้ได้โดยติดต่อผู้จัดการลูกค้าด้านเทคนิค
พ็อดวิดีโอ
ระบบจะแยกคำขอราคาเสนอสำหรับพ็อดวิดีโอที่มีโอกาสในการโฆษณาหลายรายการออกเป็นหลายรายการ เพื่อให้คำขอราคาเสนอแต่ละรายการเป็นโอกาสของโฆษณาแต่ละรายการจากพ็อดนั้น ซึ่งจะช่วยให้คุณเสนอราคาให้ได้โอกาสในการโฆษณาหลายรายการสำหรับพ็อดหนึ่งๆ
Open Measurement
Open Measurement ช่วยให้คุณระบุผู้ให้บริการบุคคลที่สามที่ให้บริการวัดผลและการยืนยันที่เป็นอิสระสำหรับโฆษณาที่แสดงในสภาพแวดล้อมแอปบนอุปกรณ์เคลื่อนที่คุณระบุได้ว่าผู้เผยแพร่โฆษณารองรับ Open Measurement ในคำขอราคาเสนอหรือไม่ โดยตรวจสอบว่าโอกาสโฆษณายกเว้นแอตทริบิวต์ OmsdkType:
OMSDK 1.0
ที่พบในแอตทริบิวต์ครีเอทีฟโฆษณาที่ผู้เผยแพร่โฆษณายกเว้นได้หรือไม่ สำหรับโปรโตคอล Authorized Buyers พารามิเตอร์นี้จะอยู่ในส่วน BidRequest.adslot[].excluded_attribute
สำหรับโปรโตคอล OpenRTB สถานะนี้จะอยู่ในส่วนแอตทริบิวต์ battr
สำหรับแบนเนอร์หรือวิดีโอ ทั้งนี้ขึ้นอยู่กับรูปแบบ
ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีตีความคำขอราคาเสนอที่มีสัญญาณ Open Measurement ได้ที่บทความในศูนย์ช่วยเหลือของ Open Measurement SDK
ตัวอย่างคำขอราคาเสนอ
ส่วนต่อไปนี้แสดงตัวอย่างคำขอราคาเสนอสำหรับโฆษณาประเภทต่างๆ