요청 처리

Google에서 애플리케이션에 입찰 요청을 보내면 실시간 입찰 상호작용이 시작됩니다. 이 가이드에서는 입찰 요청을 처리하도록 애플리케이션을 코딩하는 방법을 설명합니다.

요청 파싱

Google은 HTTP POST 요청의 바이너리 페이로드로 연결된 직렬화된 프로토콜 버퍼로 입찰 요청을 보냅니다. Content-Typeapplication/octet-stream로 설정됩니다. 입찰 요청 예시를 참고하세요.

이 요청을 BidRequest 메시지의 인스턴스로 파싱해야 합니다. BidRequest참조 데이터 페이지에서 가져올 수 있는 realtime-bidding.proto에 정의되어 있습니다. BidRequest에 대해 생성된 클래스에서 ParseFromString() 메서드를 사용하여 메시지를 파싱할 수 있습니다. 예를 들어 다음 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 사용자 ID, 언어, 지리적 위치)를 항상 사용할 수 있는 것은 아닙니다. 특정 노출에 대해 알려지지 않은 정보를 사용하는 사전 타겟팅 광고 그룹이 있는 경우 해당 광고그룹은 일치하지 않습니다. 사전 타겟팅 조건에 누락된 정보가 중요하지 않은 경우 정보가 생략된 상태로 입찰 요청이 전송됩니다.

사전 타겟팅 광고 그룹에 대한 정보는 각 AdSlotMatchingAdData 그룹에서 확인할 수 있습니다. 여기에는 Google에서 입찰 요청을 전송하도록 요청한 사전 타겟팅 광고 그룹의 첫 번째 일치하는 광고 그룹 ID가 포함됩니다. 즉, 응답이 노출에 대한 입찰에서 낙찰되면 비용이 청구되는 광고 그룹과 캠페인입니다. 특정 상황(예: BidRequest.AdSlotmatching_ad_data가 두 개 이상 있는 경우)에서는 BidResponse.AdSlot의 기여 분석을 위해 billing_id를 명시적으로 지정해야 합니다. 입찰 콘텐츠의 제약 조건에 관한 자세한 내용은 realtime-bidding.proto를 참고하세요.

사전 파일

입찰 요청은 참조 데이터 페이지에서 확인할 수 있는 사전 파일에 정의된 식별자를 사용합니다.

입찰 URL 매크로

선택적으로 BidRequest의 일부 필드를 HTTP POST 요청에 사용되는 URL에 삽입할 수 있습니다. 예를 들어 요청의 값을 사용하여 여러 백엔드를 통해 부하를 분산하는 가벼운 프런트엔드를 사용하는 경우 유용합니다. 새 매크로에 대한 지원을 요청하려면 기술계정 관리자에게 문의하세요.

Macro설명
%%GOOGLE_USER_ID%%

BidRequestgoogle_user_id로 대체되었습니다. 예를 들어 입찰자 URL은

http://google.bidder.com/path?gid=%%GOOGLE_USER_ID%%
요청 시
http://google.bidder.com/path?gid=dGhpyBhbiBleGFtGxl
등으로 대체됩니다.

Google 사용자 ID를 알 수 없는 경우 빈 문자열이 다음과 유사한 결과로 대체됩니다.

http://google.bidder.com/path?gid=
%%HAS_MOBILE%%

BidRequesthas_mobile()를 호출할 때 1 또는 0로 대체되었습니다.

%%HAS_VIDEO%%

BidRequesthas_video()를 호출할 때 1 (true) 또는 0 (false)로 대체되었습니다.

%%HOSTED_MATCH_DATA%%

BidRequesthosted_match_data 필드 값으로 대체되었습니다.

%%MOBILE_IS_APP%%

BidRequestmobile.is_app 필드에서 1 (true) 또는 0 (false)로 대체되었습니다.

거래 URL에서 모바일 앱 ID 찾기

모바일 애플리케이션 거래는 다음과 같은 URL을 보고합니다.

mbappgewtimrzgyytanjyg4888888.com

base-32 디코더를 사용하여 굵게 표시된 문자열 부분(gewtimrzgyytanjyg4888888)을 디코딩합니다.

온라인 디코더를 사용할 수 있지만 문자를 대문자로 변환하고 후행 8= 값으로 바꿔야 합니다.

따라서 이 값을 디코딩하면 다음과 같습니다.

GEWTIMRZGYYTANJYG4======
결과:
1-429610587
문자열 429610587는 iOS 앱 iFunny의 앱 ID입니다.

예를 들면 다음과 같습니다. 보고된 URL은 다음과 같습니다.

mbappgewtgmjug4ytmmrtgm888888.com
이 값을 디코딩하면 다음과 같습니다.
GEWTGMJUG4YTMMRTGM======
결과:
1-314716233
결과 314716233는 iOS 앱 TextNow의 앱 ID입니다.

거래 URL에서 모바일 앱 이름 찾기

다음은 앱 이름을 가져오는 예입니다. 보고된 URL은 다음과 같습니다.

mbappMFUXELTDN5WS42DZOBQWQLTJN4XHG3DJORUGK4Q888.com
이 값을 디코딩합니다.
MFUXELTDN5WS42DZOBQWQLTJN4XHG3DJORUGK4Q===
결과:
air.com.hypah.io.slither
결과는 Android 앱 slither.io와 동일합니다.

공개 입찰 필드

공개 입찰에 참여하는 거래소 및 네트워크 입찰자에게 전송된 입찰 요청은 표준 실시간 입찰에 참여하는 Authorized Buyers의 입찰 요청과 유사합니다. 공개 입찰 고객에게는 소수의 추가 필드가 제공되며 기존 몇 개 필드에는 대체 용도가 있을 수 있습니다. 여기에는 다음이 포함됩니다.

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를 만들려면 기술 공급업체를 선언하는 두 가지 가능성을 알고 있어야 합니다.

  1. 일부 공급업체는 신고하지 않아도 됩니다. 이러한 공급업체는 Authorized Buyers 도움말에 나와 있습니다.
  2. 다른 공급업체는 BidRequestBidResponse에 모두 선언된 경우에만 참여할 수 있습니다.
    • BidRequest에서 allowed_vendor_type 필드는 판매자가 허용하는 공급업체를 지정합니다. BidRequestallowed_vendor_type 필드에 전송될 공급업체는 Vendors.txt 사전 파일에 나열됩니다.
    • BidResponse에서 vendor_type 필드는 허용된 공급업체 중 구매자가 사용할 공급업체를 지정합니다.

입찰 요청의 예

다음 예는 사람이 읽을 수 있는 Protobuf 및 JSON 요청 샘플을 나타냅니다.

Google

OpenRTB JSON

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는 모바일 애플리케이션의 입찰 요청에서 모바일 광고 ID를 전달합니다. 모바일 광고 ID는 Authorized Buyers에서 관리하는 자바스크립트 태그의 %%EXTRA_TAG_DATA%% 매크로를 통해 전송되는 iOS IDFA 또는 Android의 광고 ID일 수 있습니다.

%%ADVERTISING_IDENTIFIER%% 매크로를 사용하면 구매자가 노출 렌더링 시 iOS IDFA 또는 Android의 광고 ID를 수신할 수 있습니다. 이 메서드는 %%EXTRA_TAG_DATA%%와 같은 암호화된 proto 버퍼 MobileAdvertisingId를 반환합니다.

message MobileAdvertisingId {
  optional bytes advertising_id = 1;
  optional int32 user_id_type = 2;
}

user_id_typeenum AdxMobileIdType에 정의된 값 중 하나입니다.

enum AdxMobileIdType {
  MOBILE_ID_UNKNOWN = 0,
  IDFA = 1,
  ANDROID_ID = 2,
};

노출 렌더링 중에 수집한 광고 ID를 사용하여 모바일 광고 ID로 사용자 목록을 만들 수 있습니다. 이러한 사용자 목록은 여러분의 서버나 Google에서 관리할 수 있습니다. Google 서버에서 사용자 목록을 만들려면 Google의 일괄 업로드 기능을 이용하세요.

모바일 광고 ID가 사용자 목록과 일치하면 이 ID를 사용하여 리마케팅을 실행할 수 있습니다.

실시간 피드백

실시간 의견은 Authorized Buyers는 물론 공개 입찰을 사용하는 거래소와 네트워크에서 사용할 수 있습니다.

입찰 응답 의견은 AdX 프로토콜과 OpenRTB의 다음 입찰 요청에서 모두 지원됩니다. OpenRTB의 경우 BidRequestExt에서 전송됩니다.

입찰 응답 피드백에서 전송되는 기본 필드 이외에도 BidResponse에서 반환되는 event_notification_token를 사용하여 입찰 응답 (AdX Proto 또는 OpenRTB)에서 맞춤 데이터를 전송할 수 있습니다. event_notification_token는 디버깅에 도움이 될 수 있는 입찰자에만 알려진 임의의 데이터입니다. 예를 들어 새 전략을 나타내는 새 타겟팅 ID 또는 입찰 ID 또는 입찰자에게만 알려진 광고 소재와 연결된 메타데이터입니다. 자세한 내용은 RTB용 OpenRTB 확장 프로토콜 버퍼 및 AdX용 AdX Proto를 참조하세요.

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에서 찾을 수 있습니다. 낙찰된 경우 가격 의견에서 선택 해제할 수 있습니다. 자세한 내용은 선택 해제 방법을 참고하세요.

실시간 의견에는 입찰 요청 ID와 다음 중 하나가 포함됩니다.

입찰 결과 실시간 피드백
구매자가 입찰을 제출하지 않았습니다. 없습니다.
구매자가 입찰에 도달하기 전에 필터링된 입찰을 제출했습니다. 광고 소재 상태 코드 (creative-status-codes.txt)
구매자가 입찰가를 제출했지만 낙찰에서 졌습니다. 광고 소재 상태 코드 79 (입찰에서 낙찰가)
구매자가 낙찰된 입찰가를 제출했습니다. 결제 가격 및 광고 소재 상태 코드 1

앱 노출 및 광고 소재 상태 코드가 83인 경우 앱 게시자가 연쇄 광고 호출 조정을 사용하고 있을 수 있으므로 낙찰된 입찰은 게시자의 패스백 폭포식 구조 체인의 다른 수요와 경쟁했을 것입니다. 입찰 시 sampled_mediation_cpm_ahead_of_auction_winner를 사용하는 방법 알아보기

샘플

다음은 지원되는 프로토콜에서 볼 수 있는 실시간 피드백 샘플입니다.

Google

OpenRTB JSON

OpenRTB 프로토콜

단일 가격 입찰을 위한 입찰 모델 구축

단일 가격 입찰에 입찰한 후 입찰이 입찰에서 필터링되지 않은 경우 minimum_bid_to_winsampled_mediation_cpm_ahead_of_auction_winner 필드를 포함한 실시간 피드백을 받게 됩니다. 이러한 신호는 노출을 낙찰하기 위해 입찰가를 얼마나 높이거나 낮출 수 있었는지 입찰 로직에 알리는 데 사용할 수 있습니다.

  • minimum_bid_to_win: 실시간 입찰 경매에서 낙찰을 받기 위해 발생했을 수 있는 최소 입찰가입니다. 낙찰을 받은 경우 낙찰을 받기 전에 제시할 수 있는 최저 입찰가입니다. 낙찰에 실패한 경우 이 가격이 낙찰가가 됩니다.
  • sampled_mediation_cpm_ahead_of_auction_winner: 미디에이션 체인에 다른 네트워크가 있는 경우 이 필드의 값은 입찰 가능한 미디에이션 네트워크 중 하나의 샘플 입찰가 중 입찰 낙찰자보다 높았으며 예상 유효노출률을 기준으로 가중치가 적용된 샘플 입찰가를 나타냅니다. 미디에이션 체인에서 채울 것으로 예상되는 네트워크가 없거나 게시자가 SDK 미디에이션을 사용하지 않는 경우에는 0으로 설정됩니다.

사용 방법

minimum_bid_to_winsampled_mediation_cpm_ahead_of_auction_winner의 가능한 값을 결정하는 데 사용되는 계산을 설명하려면 먼저 다음을 정의해야 합니다.

  • 다음은 미디에이션 체인의 CPM을 내림차순으로 나타냅니다.
    \[C_1, C_2, …, C_n\]
  • 다음은 미디에이션 체인의 CPM에 해당하는 유효노출률을 나타냅니다.
    \[f_1, f_2, …, f_n\]
  • 다음은 지정된 유효노출률을 기반으로 미디에이션 체인 요소 \(i\)에서 예상 CPM과 그 가능성을 결정하는 데 사용되는 함수입니다.
    \(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\)로 표시됩니다.
  • 2순위 입찰은 \(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) 1.00달러
입찰 준우승 (R) 0.05달러
예약 가격 / 최저 가격 (F) 0달러
낙찰받은 입찰가

다음은 낙찰된 입찰의 minimum_bid_to_winsampled_mediation_cpm_ahead_of_auction_winner 값과 확률을 계산하는 방법의 예입니다.

minimum_bid_to_win 확률
\(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
확률
\(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_winsampled_mediation_cpm_ahead_of_auction_winner 값과 확률을 계산하는 방법의 예입니다.

minimum_bid_to_win 확률
\(max(F, W) = $1.00\) \(100\%\)
sampled_mediation_cpm_
ahead_of_auction_winner
확률
\(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를 애플리케이션으로 전송되는 여러 입찰 요청으로 처리하는 것을 말합니다. 동일한 ID(Authorized Buyers RTB 프로토콜의 BidRequest.google_query_id 또는 OpenRTB 프로토콜의 BidRequestExt.google_query_id)를 유지하므로 평탄화 후 상관관계가 있는 입찰 요청을 확인할 수 있습니다.

광고 형식

일부 광고 기회에는 여러 형식이 허용됩니다. 입찰 평탄화를 사용하면 각 형식은 대상 결제 ID와 같은 속성이 요청에 지정된 형식과 관련이 있는 고유한 입찰 요청으로 전송됩니다.

다음 형식을 포함하는 입찰 요청은 개별 입찰 요청으로 평탄화됩니다.

  • 배너
  • 동영상
  • 오디오
  • 네이티브

광고 형식 평탄화의 예

다음은 광고 형식 평탄화가 없는 간소화된 OpenRTB JSON 입찰 요청을 동등한 평탄화된 요청 집합과 비교한 예시입니다.

사전 평면화

포스트 플랫텐

특가

특정 입찰자에 대한 광고 기회는 공개 입찰 외에도 다양한 거래 유형에 적용할 수 있습니다. 거래에 대한 입찰 평탄화를 사용하면 공개 입찰과 각 고정 가격 거래 유형에 대해 하나의 입찰 요청이 전송됩니다. 실제로 광고 제약조건은 입찰과 고정 가격 거래 유형 간에 다를 수 있습니다. 예를 들어 공개 입찰과 고정 가격 거래 모두에 사용할 수 있는 특정 동영상 광고 기회의 경우 입찰자는 최대 광고 기간 및 건너뛸 수 있는 광고의 허용 여부와 같은 제약조건이 다를 수 있는 경우 각각에 대해 고유한 입찰 요청을 수신합니다. 따라서 광고 기회에 평탄화를 적용하면 공개 입찰 및 고정 가격 거래의 광고 제약조건을 더 쉽게 파악할 수 있습니다.

건너뛸 수 있는 최대 동영상 재생 시간

Google의 프로토콜 및 OpenRTB 구현은 동영상 재생 시간 및 건너뛰기 가능 여부에 대해 다음 필드를 지원합니다.

시간 건너뛸 수 있는 재생 시간 건너뛰기 가능 여부
Google 프로토콜 max_ad_duration skippable_max_ad_duration video_ad_skippable
OpenRTB maxduration 해당 사항 없음 skip

즉, Google 프로토콜은 세분화된 건너뛸 수 있는 기간 및 건너뛸 수 없는 기간을 가질 수 있지만 OpenRTB 구현에는 단일 최대 기간 값만 있습니다.

입찰 평탄화 전에는 OpenRTB의 maxduration이 Google 프로토콜의 max_ad_durationskippable_max_ad_duration 필드 중 더 낮은 값으로 설정되었습니다. 이제 이 동작은 이러한 값이 다를 때 두 개의 개별 입찰 요청을 전송하는 것으로 변경되었습니다. 하나는 건너뛸 수 있는 기회에 대한 maxduration를 나타내고 다른 하나는 건너뛸 수 없는 기회에 대한 다른 입찰 요청을 나타냅니다.

다음 예는 입찰 평탄화 전후에 Google 프로토콜 요청이 OpenRTB로 변환되는 방식을 보여줍니다. 동등한 Google 프로토콜 요청의 max_ad_duration15이고 skippable_max_ad_duration60입니다.

max_ad_duration skip (true 또는 false)
평면화가 없는 원래 요청 15 true
평탄화된 요청 #1: 건너뛸 수 없음 15 false
평탄화된 요청 #2: 건너뛸 수 있음 60 true

건너뛸 수 있는 동영상 길이 입찰 요청 평탄화는 다음 조건이 충족되는 경우에만 실행됩니다.

  • 요청이 동영상을 허용합니다.
  • 건너뛰기 및 건너뛸 수 없는 동영상이 모두 허용되며 두 개의 최대 재생 시간 값은 서로 다릅니다.
  • 이 요청은 비공개 입찰 또는 공개 입찰 요건을 충족합니다.
  • 입찰자 계정에 활성 OpenRTB 엔드포인트가 있습니다.

기술계정 관리자에게 문의하여 이러한 유형의 평면화를 선택 해제할 수 있습니다.

동영상 광고 모음

여러 광고 기회가 있는 동영상 광고 모음에 대한 입찰 요청은 평탄화되어 각 입찰 요청은 해당 광고 모음의 개별 광고 기회에 대한 요청입니다. 이를 통해 특정 광고 모음에 대해 여러 광고 기회에 입찰할 수 있습니다.

개방형 측정

Open Measurement를 사용하면 모바일 앱 환경에 게재되는 광고에 독립적인 측정 및 인증 서비스를 제공하는 서드 파티 공급업체를 지정할 수 있습니다.

게시자 제외 광고 소재 속성에서 찾을 수 있는 OmsdkType: OMSDK 1.0 속성이 광고 기회에서 제외되는지 확인하여 게시자가 입찰 요청에서 Open Measurement를 지원하는지 여부를 확인할 수 있습니다. Authorized Buyers 프로토콜의 경우 BidRequest.adslot[].excluded_attribute 아래에 있습니다. OpenRTB 프로토콜의 경우 형식에 따라 배너 또는 동영상battr 속성 아래에 있습니다.

Open Measurement 신호가 포함된 입찰 요청을 해석하는 방법에 대한 자세한 내용은 Open Measurement SDK 고객센터 문서를 참조하세요.

입찰 요청 샘플

다음 섹션에서는 다양한 광고 유형에 대한 샘플 입찰 요청을 보여줍니다.

앱 배너

Google

OpenRTB JSON

OpenRTB 프로토콜

앱 전면 광고

Google

OpenRTB JSON

OpenRTB 프로토콜

앱 전면 광고 동영상

Google

OpenRTB 프로토콜

앱 네이티브

Google

OpenRTB JSON

OpenRTB 프로토콜

웹 동영상

Google

거래소 입찰자용 모바일 웹 배너

OpenRTB 프로토콜