构建响应

您的应用处理来自 Google 的出价请求后,必须构建并发送响应。本指南介绍了如何编写应用代码以构建响应。

创建 Protobuf BidResponse 消息

Authorized Buyers 会将 BidRequest 作为 HTTP POST 的消息正文发送出去。如果您的出价端点配置为使用 protobuf 格式,您的应用必须发送一个响应,其中 Content-Type 标头设置为 application/octet-stream,并且消息正文由序列化协议缓冲区组成。协议缓冲区是 openrtb.proto 中定义的 BidResponse 消息。您的应用必须针对每个 BidRequest 返回可解析的 BidResponse。超时和无法解析的响应会被视为错误,Google 会对错误率较高的出价方进行节流。

如果您不想对展示出价,则必须返回空的 HTTP 204 响应。您可以从参考数据页面获取 openrtb.proto

广告素材 ID

您的 BidResponse 通过 BidResponse.seatbid.bid.crid 字段(限制为 64 字节)指定广告素材。即使是类似的广告素材,如果在任何显著特征(包括但不限于尺寸、声明的网址、广告素材属性和供应商类型)方面存在差异,也必须为此字段提供不同的值。换句话说,如果有任何两个广告满足以下条件,您就必须为其指定不同的广告素材 ID:

  • 外观或行为有所不同。
  • 渲染到不同的图片。
  • 以不同的方式呈现(例如,一个广告由图片组成,另一个广告则是视频)。

在设计应用时,您应确定一种系统的标识符生成方法,该方法应适用于您计划提交的广告素材类型。

广告属性

Google 建议您声明广告素材属性,以便使用 BidResponse.seatbid.bid.apisBidResponse.seatbid.bid.attr 的组合或 BidResponse.seatbid.bid.ext.attribute 扩展来描述广告的特性和定位条件。以下内容介绍了如何声明属性:

  • VPAID
    BidResponse.seatbid.bid.apis 设置为 VPAID_1VPAID_2。对于 JSON 格式,此值可以分别设置为 12
  • MRAID
    BidResponse.seatbid.bid.apis 设置为 MRAID_1,或将其设置为 3(对于 JSON 格式)。
  • SIZELESS
    BidResponse.seatbid.bid.attr 设置为 RESPONSIVE,或将其设置为 18(JSON 格式)。
  • PLAYABLE
    这通过将 BidResponse.seatbid.bid.attr 设置为 USER_INTERACTIVE13(对于 JSON 格式)来指明。

如需了解如何获取有关广告素材检测到的属性的反馈,请参阅 Creatives 资源

公开出价字段

参与公开出价的广告交易平台和广告联盟出价方发送的出价响应与参与标准实时出价的 Authorized Buyers 买方发送的出价响应类似。公开出价客户可以指定少量其他字段,并且一些现有字段可能有其他用途。其中包括:

OpenRTB Authorized Buyers 详细信息
BidResponse.imp[].pmp.deals[].id BidResponse.ad[].adslot[].exchange_deal_id

广告交易平台命名空间中的交易 ID,与此出价相关联并报告给发布商。

BidResponse.seatbid[].bid[].ext.exchange_deal_type BidResponse.ad[].adslot[].exchange_deal_type

向发布商报告的交易类型,会影响交易在竞价中的处理方式。

BidResponse.seatbid[].bid[].ext.third_party_buyer_token BidResponse.ad[].adslot[].third_party_buyer_token 如果作为公开出价方参与竞价的广告交易平台充当中介,则此令牌用于识别最终第三方买方信息。此值从第三方买方处获取,必须在出价响应中保持不变,以便传递给 Google。

建议

  • 在服务器上启用持久性 HTTPS 连接(也称为“保持连接”或“连接重复使用”)。将超时时间至少设置为 10 秒;在许多情况下,设置更高的值会很有帮助。Google 会在应用的初始延迟时间测试期间验证这一点,因为 Authorized Buyers 会以较高的速率发送请求,并且需要避免为每个请求建立单独的 TCP 连接而产生的延迟时间开销。
  • 添加可选的展示跟踪网址,以跟踪展示何时呈现,而不是出价方何时胜出。由于胜出和呈现之间存在流失,因此这样可以获得更准确的跟踪统计信息。

  • 请确保出价方代码不依赖于已废弃的字段,因为这可能会导致出价失败并出现错误。
  • BidResponse 中添加 BidResponse.seatbid.bid.wBidResponse.seatbid.bid.h。如果请求包含多个广告尺寸,则对该请求的 BidResponse 必须包含这些字段,否则将从竞价中移除。
  • 将响应大小限制在 8 KB 以下。非常大的响应可能会增加网络延迟时间并导致超时。
  • 请遵循针对需要 SKAdNetwork 归因的 iOS 广告资源出价的准则

出价响应示例

以下示例展示了 Protobuf 和 JSON 请求的可读取示例。

OpenRTB Protobuf

OpenRTB JSON

Google

重要提示:示例中所述的 Protobuf 消息在此处以人类可读的文本表示。不过,消息并非以这种方式通过线路发送。使用 Google 或 OpenRTB Protobuf 格式时,系统只接受序列化的 BidResponse 消息。

您可以使用以下 C++ 代码创建和序列化 BidResponse 消息:

BidResponse bid_response;
// fill in bid response with bid information
string post_response;
if (bid_response.SerializeToString(&post_response)) {
  // respond to the POST with post_response as the content
} else {
  // return an error to the POST
}

指定广告素材

您的出价响应会指定在您的出价胜出时要投放的广告素材。您的出价必须包含一种受支持的广告格式(AMP、视频、原生)。在此示例中,我们使用 html_snippet 字段指定广告素材。

或者,您也可以根据广告格式,使用以下一个字段指定广告素材:

  • SDK 呈现的广告
    • BidResponse.seatbid.bid.ext.sdk_rendered_ad
  • AMP
    • BidResponse.seatbid.bid.amp_ad_url
  • 视频
    • BidResponse.seatbid.bid.adm
  • 原生广告
    • BidResponse.seatbid.bid.adm_native

BidResponse.seatbid.bid.adm 字段中使用 HTML 代码段指定托管在您自己的服务器上的广告。该代码段封装在插入网页中的 iFrame 中,以便在网页加载时检索和呈现广告。您必须精心制作 HTML 代码段,以便广告(横幅广告或插页式广告)在 iFrame 中正确呈现,并且尺寸与您要出价的广告位相称。

此外,在以下情况下,出价响应中声明的广告尺寸必须与出价请求中的某个尺寸组合完全一致:

  • 广告是常规横幅广告(而非视频广告、原生广告或插页式广告)。
  • 出价方已在出价响应中声明大小。每当请求中包含多个尺寸时,都必须声明尺寸。
  • 插页式广告是例外情况。对于插页式广告,宽度必须至少为屏幕宽度的 50%,高度至少为屏幕高度的 40%。

您可以使用任何能够正常呈现的有效 HTML 代码指定 HTML 代码段广告素材,但请注意创建 BidResponse 消息部分中对指定 crid 字段的限制。这类函数的一个用途是将额外信息放入在呈现广告时从服务器提取的网址的参数中。这样,您就可以将与展示相关的任意数据传回自己的服务器。

针对在出价响应中返回的 HTML 代码段的大多数政策与针对第三方广告的政策相同。如需了解详情,请参阅“已获授权的买方”计划准则第三方广告投放要求在广告中声明点击到达网址

指定宏

宏是嵌入到一些出价响应字段中的格式化文本,这些字段包含网址,这些网址会在广告投放时替换为相关值。例如,如果您的胜出出价在出价中包含的 HTML 代码段广告素材中包含 AUCTION_PRICE 宏,系统会将该宏替换为一个值,您可以对该值进行解密,以确定您在竞价中为该展示支付的金额。

您可以在以下字段中添加宏:

  • BidResponse.seatbid.bid.adm

    HTML 代码段、原生广告、视频网址和视频 VAST XML 格式支持宏。

  • BidResponse.seatbid.bid.adm_native.eventtrackers.url

  • BidResponse.seatbid.bid.adm_native.imptrackers

  • BidResponse.seatbid.bid.ext.amp_ad_url

    AMP 广告素材仅支持 Google 专用 WINNING_PRICEWINNING_PRICE_ESC 宏。

  • BidResponse.seatbid.bid.burl

  • BidResponse.seatbid.bid.ext.impression_tracking_url

    如果您需要多个结算网址,请使用此属性(而非 BidResponse.seatbid.bid.burl)。

例如,您可以通过在用于提取广告素材的网址中嵌入 ${MACRO},将宏作为 HTML 代码段的一部分包含在内,其中 MACROOpenRTB 规范中所述的受支持宏之一。

Google RTB 宏

除了 OpenRTB 规范中列出的宏之外,Google 还支持其他宏。这些宏的格式不同,如果嵌入到网址中,则会显示为 %%MACRO%%。下表介绍了这些宏:

说明
ADVERTISING_IDENTIFIER 允许买方在广告展示时接收 iOS IDFA 或 Android 的广告 ID。 如需了解详情,请参阅解密广告主标识符
CACHEBUSTER 随机无符号四字节整数的字符串表示法。
CLICK_URL_UNESC

广告的不转义点击后到达网址。在代码段中,第三方点击跟踪网址的转义版本应直接跟在宏后面。

例如,如果第三方点击跟踪网址为 http://my.adserver.com/some/path/handleclick?click=clk,则可以在宏调用后将以下代码与第三方点击跟踪网址的单重转义版本搭配使用:

<a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

在广告投放时,此字段会展开为:

<a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

该网址会先向 Google 注册点击,然后重定向到第三方点击跟踪网址。

CLICK_URL_ESC

广告的转义点击后到达网址。如果您需要先将值传递到另一个随后会返回重定向的服务器,请使用此宏而非 CLICK_URL_UNESC

例如,您可以在 HTML 代码段中使用以下代码:

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a>

在广告投放时,此字段会展开为:

<a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a>

这会向 my.adserver.com 注册点击,然后 my.adserver.com 将负责重定向到 google_click_url 参数中传递的网址。这假定 my.adserver.com 会对 google_click_url 参数进行转义。

您可以在 %%CLICK_URL_ESC%% 后面附加经过两次转义的网址。my.adserver.com 完成转义后,系统会将网址的单转义版本附加到 google_click_url。提取 google_click_url 后,它会再次转义,然后重定向。

CLICK_URL_ESC_ESC

广告的双重转义网址。如果您需要先将值传递到另一个随后会返回重定向的服务器,请使用此宏而非 CLICK_URL_UNESC

例如,您可以在 HTML 代码段中使用以下代码:

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a>

在广告投放时,此字段会展开为:

<a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a>
SCHEME 如果出价请求不需要 SSL,则扩展为 http:;如果出价请求需要 SSL,则扩展为 https:
SITE 内容网址的域名,经过了网址转义;对于匿名广告资源,则为匿名 ID。
SITE_URL 已弃用。已被 SITE 宏取代,后者提供相同的功能。
TZ_OFFSET 时区偏移量。
VERIFICATION

在生产环境中和在验证流水线中扫描广告素材时,值不同。格式为:%%?VERIFICATION:true-val:false-val%%,其中 true-valfalse-val 可以使用宏以外的任何值,包括空字符串。对于公开出价,我们建议广告交易平台使用此宏;广告交易平台使用此宏后,需求方平台无需进行任何更改。

例如,如果广告素材包含 %%?VERIFICATION:-1:5000%%,则在投放时文本替换项将为 5000,在验证流水线中将为 -1。这是为了区分这两组 ping。

WINNING_PRICE

编码格式的展示费用(即 CPI,而不是每千次展示费用),以账号币种的百万分之一表示。例如,以 5 美元赢得的每千次展示费用出价相当于 5 百万个每千次展示费用出价宏,或者 5000 个 CPI 宏。在这种情况下,WINNING_PRICE 的解码值将为 5,000。胜出价格是以 CPI 指定的。

如需解析此宏,您需要实现一个用于解密价格确认的应用。如需了解详情,请参阅解密价格确认页面。

WINNING_PRICE_ESC 经过网址转义的 WINNING_PRICE

Google 要求您在第三方投放的广告的广告素材中使用 CLICK_URL_UNESCCLICK_URL_ESC 宏。Google 使用 CLICK_URL 宏进行点击跟踪。

宏中的网址转义使用以下方案:

  • 空格字符会被加号 (+) 替换。
  • 字母数字字符(0-9、a-z、A-Z)和集合 !()*,-./:_~ 中的字符保持不变。
  • 所有其他字符均替换为 %XX,其中 XX 是表示相应字符的十六进制数字。

发布商限制和要求

出价请求包含有关发布商在竞价中对广告素材施加的限制和要求的类型的信息。

  • BidRequest.bcat
    • 您可以将此字段指定的屏蔽类别与使用实时出价 API 的 detectedCategories 字段为您提交的广告素材检测到的类别进行比较。
  • BidRequest.imp.ext.allowed_vendor_type
  • BidRequest.imp.secure
    • 在实践中,此值始终会设为 true,因为 Google 要求所有广告素材都支持 SSL。
  • BidRequest.imp.{audio/banner/native/video}
  • BidRequest.imp.{audio/banner/native/video}.api
  • BidRequest.imp.{audio/banner/native/video}.battr
  • BidRequest.imp.{audio/banner/video}.mimes

切勿出价投放包含受限功能的广告。对于允许的功能(例如供应商类型),仅当广告的供应商类型在 BidRequest 中的 allowed_vendor_type 列表中时,才返回相应广告。只有通过填充 BidRequest.imp.banner 等字段在出价请求中指定的广告格式才应包含在出价中。如需了解详情,请参阅 BidRequest 协议缓冲区定义中对这些字段的注释。

如果 BidResponse 中返回了广告,您必须在 BidResponse 中准确设置 BidResponse.seatbid.bid.attrBidResponse.seatbid.bid.cat 以及 BidResponse.seatbid.bid.adomainBidResponse.seatbid.bid.adm_native.link.url 字段。如果广告对这些字段有多个适用值,则必须包含所有值。如需了解详情,请参阅 BidResponse 协议缓冲区定义中对这些字段的注释。系统会舍弃未设置这些字段的响应。

Open Measurement

借助 Open Measurement,您可以指定为投放到移动应用环境的广告提供独立衡量和验证服务的第三方供应商。

支持的广告格式包括视频广告、横幅广告和插页式广告。如需详细了解如何在包含这些格式的出价响应中使用 Open Measurement,请参阅 Open Measurement SDK 帮助中心文章。

出价响应示例

以下部分显示了不同广告类型的出价响应示例。

应用横幅广告

OpenRTB Protobuf

OpenRTB JSON

Google

应用插页式广告

OpenRTB Protobuf

OpenRTB JSON

Google

应用插页式视频广告

OpenRTB Protobuf

OpenRTB JSON

Google

原生应用

OpenRTB Protobuf

OpenRTB JSON

Google

网络视频

OpenRTB Protobuf

OpenRTB JSON

Google

适用于广告交易平台出价方的移动网站横幅广告

OpenRTB Protobuf

OpenRTB JSON