ประมวลผลคำขอ

การโต้ตอบในการเสนอราคาแบบเรียลไทม์จะเริ่มขึ้นเมื่อ 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%%

แทนที่ด้วย google_user_id จาก BidRequest ตัวอย่างเช่น URL ของผู้เสนอราคา 

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%%

แทนที่ด้วย 1 หรือ 0 เมื่อโทรหา has_mobile() ของ BidRequest
%%HAS_VIDEO%%

แทนที่ด้วย 1 (จริง) หรือ 0 (เท็จ) เมื่อเรียกใช้ has_video() ของ BidRequest
%%HOSTED_MATCH_DATA%%

แทนที่ด้วยค่าของช่อง hosted_match_data จาก BidRequest
%%MOBILE_IS_APP%%

แทนที่ด้วย 1 (จริง) หรือ 0 (เท็จ) จากช่อง mobile.is_app ของ BidRequest

ค้นหารหัสแอปบนอุปกรณ์เคลื่อนที่จาก 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 ของผู้เผยแพร่โฆษณาตามด้วยลำดับชั้นของหน่วยโฆษณา โดยคั่นด้วยเครื่องหมายทับ

ตัวอย่างเช่น ข้อความนี้จะปรากฏโดยมีการจัดรูปแบบคล้ายกับ /1234/cruises/mars
BidRequest.user.data[].segment[] BidRequest.adslot[].exchange_bidding.key_value[]

คู่คีย์-ค่าซ้ำที่ส่งจากผู้เผยแพร่โฆษณาไปยังผู้เสนอราคาแลกเปลี่ยน

คุณระบุได้ว่าค่าดังกล่าวเป็นคู่คีย์-ค่าที่ผู้เผยแพร่โฆษณาส่งเมื่อตั้งค่า BidRequest.user.data[].name เป็น “Publisher Passed”

ประกาศผู้ให้บริการที่ได้รับอนุญาต

ผู้ให้บริการเทคโนโลยีที่ให้บริการ เช่น การวิจัย รีมาร์เก็ตติ้ง และการแสดงโฆษณา อาจมีบทบาทในการโต้ตอบระหว่างผู้ซื้อกับผู้ขาย อนุญาตเฉพาะผู้ให้บริการที่ Google ได้ตรวจสอบแล้วสำหรับการเข้าร่วมการโต้ตอบของ Authorized Buyers

เพื่อทำความเข้าใจBidRequestและสร้างBidResponse คุณต้องตระหนักถึงความเป็นไปได้ 2 ประการในการประกาศผู้ให้บริการเทคโนโลยี ดังนี้

  1. ผู้ให้บริการบางรายไม่จำเป็นต้องได้รับแจ้ง ผู้ให้บริการเหล่านี้แสดงรายการอยู่ในศูนย์ช่วยเหลือของ Authorized Buyers
  2. ผู้ให้บริการรายอื่นๆ จะเข้าร่วมได้ต่อเมื่อมีการประกาศยืนยันทั้งใน BidRequest และ BidResponse ต่อไปนี้
    • ในช่อง BidRequest ช่อง allowed_vendor_type จะระบุผู้ให้บริการที่ผู้ขายอนุญาต ผู้ให้บริการที่จะส่งในช่อง allowed_vendor_type ของ BidRequest จะมีรายชื่ออยู่ในไฟล์พจนานุกรม Vendors.txt
    • ในช่อง BidResponse ช่อง vendor_type จะระบุผู้ให้บริการที่ได้รับอนุญาตที่ผู้ซื้อตั้งใจจะใช้

ตัวอย่างคำขอราคาเสนอ

ตัวอย่างต่อไปนี้แสดงตัวอย่างที่มนุษย์อ่านได้ของคำขอ Protobuf และ JSON

Google

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

สำหรับการแสดงผลแอปและรหัสสถานะครีเอทีฟโฆษณา 83 ผู้เผยแพร่แอปอาจใช้การแสดงโฆษณาสื่อกลางตามลำดับขั้นอยู่ ดังนั้นราคาเสนอที่ชนะก็จะแข่งขันกับความต้องการอื่นๆ ใน Waterfall ของรายการส่งคืนของผู้เผยแพร่โฆษณา ดูวิธีใช้ sampled_mediation_cpm_ahead_of_auction_winner เมื่อเสนอราคา

ตัวอย่าง

ต่อไปนี้คือตัวอย่างของความคิดเห็นแบบเรียลไทม์ที่เห็นในโปรโตคอลที่รองรับ

Google

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_
of_auction_winner
\(\{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_
of_auction_winner
\(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_
ahead_of_auction_winner		 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_
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\%\)

การแยกการเสนอราคา

การแยกการเสนอราคาอธิบายการประมวลผล 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

ตัวอย่างคำขอราคาเสนอ

ส่วนต่อไปนี้แสดงตัวอย่างคำขอราคาเสนอสำหรับโฆษณาประเภทต่างๆ

แบนเนอร์ของแอป

Google

JSON ของ OpenRTB

โปรโตคอล OpenRTB

โฆษณาคั่นระหว่างหน้าในแอป

Google

JSON ของ OpenRTB

โปรโตคอล OpenRTB

โฆษณาวิดีโอคั่นระหว่างหน้าในแอป

Google

โปรโตคอล OpenRTB

เนทีฟของแอป

Google

JSON ของ OpenRTB

โปรโตคอล OpenRTB

วิดีโอบนเว็บ

Google

แบนเนอร์เว็บบนอุปกรณ์เคลื่อนที่สำหรับผู้เสนอราคาแลกเปลี่ยน

โปรโตคอล OpenRTB