处理请求

当 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 用户 ID、语言或地理位置并非始终可用。如果您有 预定位广告组，而这些广告组使用的是 展示，那么这些广告组将不匹配。在缺少 与预定位条件无关，那么出价请求就是 （省略了信息）。

有关预定位广告组的信息，请访问 每个AdSlot的“MatchingAdData”组。它包含 提示 Google 执行以下操作的预定位广告组的首个匹配的广告组 ID： 发送出价请求，也就是 您的响应在针对相应展示的竞价中胜出。在特定条件下 您需要为容器明确指定 billing_id BidResponse.AdSlot中的归因，例如，当 BidRequest.AdSlot 有多个 matching_ad_data。 如需详细了解对出价内容的限制，请参阅 realtime-bidding.proto。

字典文件

出价请求会使用字典文件中定义的标识符 详情请参阅参考数据 页面。

出价网址宏

（可选）BidRequest 的某些字段可以插入 HTTP POST 请求中使用的网址。举例来说，如果您使用 使用一个值在多个后端之间进行负载均衡的轻量级前端 。如需获得以下方面的支持，请与您的技术支持客户经理联系 新宏。

宏说明
%%GOOGLE_USER_ID%%

已替换为google_user_id 从 BidRequest 获取。例如，出价工具网址 

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

在调用时替换为 1 或 0 BidRequest的has_mobile()。
%%HAS_VIDEO%%

已替换为 1 (true) 或 0 (false) 调用 BidRequest 的 has_video() 时。
%%HOSTED_MATCH_DATA%%

替换为 hosted_match_data 字段的值 从 BidRequest 获取。
%%MOBILE_IS_APP%%

已替换为 1 (true) 或 0 (false) （来自 BidRequest 的 mobile.is_app 字段）。

从交易网址中查找移动应用 ID

移动应用交易会报告如下网址：

mbappgewtimrzgyytanjyg4888888.com

使用 base-32 解码器解码字符串中以粗体显示的部分 （gewtimrzgyytanjyg4888888）。

您可以使用在线 解码器，但是您需要将字母大写并替换结尾 值为 = 的 8。

因此，对该值进行解码： 

GEWTIMRZGYYTANJYG4======
 会得到以下结果： 
1-429610587
 字符串 429610587 是 iOS 应用的 ID iFunny。

再看下面一个示例。被举报的网址如下： 

mbappgewtgmjug4ytmmrtgm888888.com
 对此值进行解码： 
GEWTGMJUG4YTMMRTGM======
 会得到以下结果： 
1-314716233
 结果 314716233 是 iOS 应用的 ID TextNow。

从交易网址中查找移动应用名称

下面是一个获取应用名称的示例。被举报的网址如下所示： 

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. 其他供应商只有同时在 BidRequest 和 BidResponse： <ph type="x-smartling-placeholder">
      </ph>
    • 在 BidRequest 中，allowed_vendor_type 字段用于指定卖方允许的供应商。将接收的供应商 BidRequest 的 allowed_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 可以是 iOS IDFA 或 <ph type="x-smartling-placeholder"></ph> Android 的广告 ID，该 ID 通过 %%EXTRA_TAG_DATA%% 宏， Authorized Buyers。

%%ADVERTISING_IDENTIFIER%%宏可让买方 在广告展示时呈现 iOS IDFA 或 Android 广告 ID。它会返回一个 加密的 proto 缓冲区 MobileAdvertisingId，如 <ph type="x-smartling-placeholder"></ph> %%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,
};

您可以使用广告 ID，根据移动广告 ID 创建用户名单 您在展示呈现期间收集的素材资源这些用户列表可以 您的服务器或我们的服务器上要在 Google 服务器上创建用户名单，您可以使用 批量上传工具

如果移动广告 ID 与某个用户名单匹配，您就可以使用它来投放 。

实时反馈

Authorized Buyers 买方以及 广告交易平台和广告联盟

两者的后续出价请求均支持出价响应反馈 AdX 协议和 OpenRTB对于 OpenRTB，请求会以 BidRequestExt。

除了在出价响应反馈中发送的默认字段外，您还可以 还会在出价响应中（在 AdX Proto 或 OpenRTB 中）发送自定义数据 event_notification_token（返回 BidResponse。event_notification_token为 可能有助于调试、 示例：代表新策略的新定位 ID 或出价 ID，或者 与广告素材相关联的元数据。如需了解详情，请参阅 请参阅 OpenRTB 适用于 RTB 和 AdX Proto 的 Extensions Protocol Buffer 。

当 Authorized Buyers 买方向出价方发送出价请求后，该出价方会做出回复 并使用 BidResponse。如果出价方启用了实时反馈功能 在后续出价请求中，Authorized Buyers 会发送 返回 BidResponseFeedback 消息，如下所示：

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;
}

在此消息中，您应检查的第一个字段是 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_win和 sampled_mediation_cpm_ahead_of_auction_winner 如果出价 未被滤除而无法参与竞价。这些信号可用于了解您的 根据出价逻辑确定您的出价可以提高多少或 赢得展示机会。

  • minimum_bid_to_win：本可达到的最低出价 赢得实时出价竞价的机会。如果您在竞价中胜出， 就是您在赢得竞价时原本可以设置的最低出价。如果您丢失了 系统就会选择胜出的出价
  • sampled_mediation_cpm_ahead_of_auction_winner：如果存在 中介链中的其他广告联盟， 此字段的值是代表来自某个 符合条件的中介广告联盟（权重高于竞价胜出者） 预期填充率如果 中介链预计会填充广告，或者如果发布商未使用 SDK 中介。

工作原理

为了说明用于确定可能值的计算方法， 适用于minimum_bid_to_win和 sampled_mediation_cpm_ahead_of_auction_winner，我们首先需要 定义以下内容：

  • 下表按降序显示了中介链中的 CPM：
    \[C_1, C_2, …, C_n\]
  • 下面显示的是 中介链：
    \[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\%\)

假设实时出价竞价的结果如下：

实时出价竞价 每千次展示费用
竞价胜出者 (W) $1.00
竞价亚军 (R) $0.05
预订价格 / 底价 (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转换为多个出价请求 应用。因为它们保留相同的 ID （Authorized Buyers 实时出价协议中的 BidRequest.google_query_id 或 OpenRTB 协议中的 BidRequestExt.google_query_id），您可以 确定哪些出价请求在拆分后是相关的。

广告格式

某些广告机会可以接受多种格式。启用出价拆分功能后 格式在单独的出价请求中发送，并且该表单中 结算 ID 与请求中指定的格式相关。

包含以下格式的出价请求将被拆分为 不同的出价请求：

  • 横幅
  • 视频
  • 音频
  • 原生

广告格式扁平化示例

下例显示了不含广告的简化 OpenRTB JSON 出价请求 格式扁平化（与一组等效的扁平化请求相比）：

预先扁平

后扁平

特惠

某个出价方的广告机会可能适用于各种交易 以及公开竞价拆分交易的出价后，系统将只使用 1 个出价 为公开竞价发送一个请求，并为每种固定价格类型 交易在实践中，竞价与固定价格之间的广告限制可能有所不同 例如，您可以查找特定视频广告机会 公开竞价和固定价格交易，那么出价方将获得 针对 2023 年 5 月 24 日之前 允许可跳过的广告可能有所不同因此，会对广告应用扁平化处理 可让您更轻松地找出 和固定价格交易

可跳过式视频广告时长上限

Google 的协议和 OpenRTB 实现支持以下字段 ：

时长 可跳过时长 可跳过性
Google 协议 max_ad_duration skippable_max_ad_duration video_ad_skippable
OpenRTB maxduration 不适用 skip

这意味着，虽然 Google 协议 和不可跳过的时长，OpenRTB 实施只会 最大时长值。

在拆分出价之前，OpenRTB 的 maxduration 会设置为 Google 协议的 max_ad_duration 和 skippable_max_ad_duration 字段。现在，这一行为已更改为 当这些值不同时，发送两个单独的出价请求：一个表示 maxduration 表示可跳过广告，另一个表示不可跳过广告 优化建议。

以下示例展示了 Google 协议如何转换 和 OpenRTB 协议的方法保持一致。等效的 Google 协议 请求的 max_ad_duration 为 15， 第 skippable_max_ad_duration 项，共 60 项。

示例 max_ad_duration skip（true 或 false）
未进行展平的原始请求 15 true
拆分的请求 1：不可跳过 15 false
扁平化请求 2：可跳过 60 true

仅当符合以下条件时，系统才会按可跳过视频广告时长出价请求拆分 满足以下条件：

  • 该请求允许播放视频。
  • 允许跳过和不跳过的视频， 但值不同。
  • 此请求符合私下竞价或公开竞价条件。
  • 出价方账号包含有效的 OpenRTB 端点。

要选择停用此类扁平化， 客户经理。

视频广告连播

对于包含多个广告机会的视频广告连播，系统会拆分出价请求 以确保每个出价请求都是针对相应广告连播中的单个广告机会的 这样，您就可以针对特定广告连播对多个广告机会进行出价。

开放式衡量

通过 Open Measurement，您可以指定提供 针对投放到移动应用的广告提供独立的衡量和验证服务 环境

您可以确定发布商是否支持在出价中使用开放式衡量 请求，方法是检查广告机会是否排除了“发布商可排除”中的 OmsdkType: OMSDK 1.0 属性 广告素材属性。对于 Authorized Buyers 协议，此路径为 在 BidRequest.adslot[].excluded_attribute 下找到。对于 OpenRTB 协议，可在 battr 属性下找到 对于横幅广告，或者 Video，具体取决于 格式。

如需详细了解如何解读包含“公开出价”的出价请求 衡量信号，请参阅 Open Measurement SDK 帮助中心文章。

出价请求示例

以下各部分显示了不同广告类型的出价请求示例。

应用横幅广告

Google

OpenRTB JSON

OpenRTB 协议缓冲区

应用插页式广告

Google

OpenRTB JSON

OpenRTB 协议缓冲区

应用插页式视频广告

Google

OpenRTB 协议缓冲区

应用原生

Google

OpenRTB JSON

OpenRTB 协议缓冲区

网络视频

Google

广告交易平台出价工具的移动网站横幅广告

OpenRTB 协议缓冲区