构建响应

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

创建出价响应消息

Authorized Buyers 将 BidRequest 作为 HTTP POST 的消息正文发送出去。应用发送的响应必须将 Content-Type 标头设置为 application/octet-stream,并且消息正文必须由序列化协议缓冲区组成。协议缓冲区是 realtime-bidding.proto 中定义的 BidResponse 消息。您的应用必须返回一个可解析的 BidResponse 来响应每个 BidRequest。无法解析的超时和响应会被视为错误,Google 会对错误率较高的出价工具加以限制。

如果您不想对展示机会出价,可以单独设置 processing_time_ms 字段,并将其他所有字段留空。您可以从参考数据页面获取 realtime-bidding.proto

广告素材 ID

您的 BidResponse 通过 buyer_creative_id 字段(上限为 64 字节)指定广告素材。即使是类似的广告素材,只要任何显著的特征(包括但不限于:尺寸、声明的网址、广告素材属性和供应商类型)不同,就必须为 buyer_creative_id 提供唯一的值。换言之,只要任意两个广告符合以下情况,您就必须为其指定不同的广告素材 ID:

  • 外观或行为方式有所不同。
  • 渲染到不同的图片。
  • 采用不同的呈现方式(例如,一个广告包含图片,另一个广告包含 Flash)。

在设计应用时,您应该确定一种系统化方式来生成对您计划提交的各类广告素材有意义的标识符。

广告属性

您必须在 BidResponse.Ad.attribute 中声明可充分说明广告特征及其定位条件的广告素材属性。必须声明的属性如下(另请参阅 buyer-declarable-creative-attributes.txt 中支持的属性的完整列表):

  • 7 Tagging: IsTagged
    广告包含一个像素(又称网络信标),以便为后续再营销创建一个 Cookie ID 列表。
  • 8 Remarketing: IsRemarketing
    广告根据用户的 Cookie ID 或设备 ID 来定位他们,此处的 Cookie ID 或设备 ID 列表表示之前曾经与买方拥有或代表的网站进行过互动的一组消费者。
  • 9 UserInterestTargeting: IsUserInterestTargeted
    广告会根据消费者的 Cookie ID 或设备 ID 来定位他们,此处的 Cookie ID 或设备 ID 列表代表了被买家定义为常见兴趣群体的一组消费者。
  • 30 InstreamVastVideoType: Vpaid
    该广告需要支持 VPAID 才能呈现。
  • 32 MraidType: MRAID
    广告需要使用 MRAID API 才能呈现。

此外,以下属性受支持,但无需进行声明,因为 Authorized Buyers 会自动检测这些属性,并根据检测到的值(而不是您的声明)屏蔽(或允许)您的广告素材。请参阅 Creatives API,了解如何获取有关检测到的广告素材属性的反馈。

  • 34 RichMediaCapabilityType: RichMediaCapabilityFlash
    广告需要 Flash 支持才能呈现。
  • 50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
    广告无需 Flash 即可呈现。
  • 47 RichMediaCapabilityType: RichMediaCapabilitySSL
    广告能够在 SSL 网页上呈现。请注意,Authorized Buyers 会将此属性的声明值不同的广告素材视为不同的广告素材(这些广告素材将分别接受审核,且具有不同的审批状态)。因此,如果您使用同一广告素材的 SSL 和非 SSL 版本进行出价,则应相应地声明此属性,以使这一区别正确反映在 AdX 中。

公开出价字段

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

OpenRTB Authorized Buyers 具体说明
BidResponse.imp[].pmp.deals[].id BidResponse.ad[].adslot[].exchange_deal_id

广告交易平台命名空间中的交易 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.Ad.widthBidResponse.Ad.height。对于包含多个广告尺寸的请求,BidResponse 必须包含 widthheight 值,否则系统会将其从竞价中移除。
  • 将响应大小限制在 8K 以下。非常大的响应可能会增加网络延迟时间并导致超时。
  • 遵循对需要 SKAdNetwork 归因的 iOS 广告资源出价指南

出价响应示例

以下示例表示人类可读的 Protobuf 和 JSON 请求示例。

Google

OpenRTB JSON

OpenRTB 协议缓冲区

重要提示:示例中所述的 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.Ad.sdk_rendered_ad
  • AMP
    • BidResponse.Ad.amp_ad_url
  • 视频
    • BidResponse.Ad.video_url
    • BidResponse.Ad.video_vast_xml
  • 原生广告
    • BidResponse.Ad.native_ad

BidResponsehtml_snippet 字段中使用 HTML 代码段指定托管在您自己的服务器上的广告。该代码段位于插入网页的 iframe 中,以便系统在网页加载时检索并呈现广告。您必须精心制作 HTML 代码段,以使广告(横幅广告或插页式广告)在 iframe 内正确呈现,并以适合您出价的广告位的尺寸呈现。

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

  • 广告是常规横幅广告(而非视频广告、原生广告或插页式广告)。
  • 出价方已在出价响应中声明了尺寸。如果请求中存在多个尺寸,则必须声明尺寸。
  • 插页式广告例外。对于插页式广告,其宽度必须至少为屏幕宽度的 50%,高度必须至少为屏幕高度的 40%。

html_snippet 字段支持可正确呈现的任何有效 HTML 代码,但请注意,在 Create BidResponse message 部分中指定 buyer_creative_id 字段的相关限制。这样做的一个用途是将额外的信息添加到在呈现广告的过程中从服务器提取的网址的参数中。这样,您就可以将与展示有关的任意数据传回您自己的服务器。

对于在出价响应中返回的 HTML 代码段,其适用的政策大多与第三方广告的政策相同。如需了解详情,请参阅 Authorized Buyers 计划指南第三方广告投放要求在广告中声明点击后到达网址

指定宏

用于定义广告素材的 HTML 代码段可包含一个或多个特殊结构,这些特殊结构称为“宏”。在投放广告时,系统会使用这些值替代宏。例如,您的客户端出价应用可以使用 WINNING_PRICE 宏来确定为广告支付的费用(如果在竞价中胜出)。如需解析此宏,您需要实现一个用于解密价格确认的应用。如需了解详情,请参阅解密价格确认页面。

%%MACRO%% 格式将宏指定为 HTML 代码段的一部分,其中 MACRO 是下表中列出的受支持宏之一。

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

如需使用宏,请将其添加到广告中,以便在用户点击它时获取网址。提取的返回值是指向您附加到 CLICK_URL 的另一个网址的重定向值。

说明
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,而不是 CPM),以帐号币种的微单位表示。例如,5 美元的胜出 CPM 相当于 5,000,000 微单位 CPM,或 5,000 微单位 CPI。在这种情况下,WINNING_PRICE 的解码值为 5,000。 胜出价格以每次安装费用的形式指定。
WINNING_PRICE_ESC 经过网址转义的 WINNING_PRICE

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

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

发布商限制

发布商使用 BidRequest 传递有关允许哪些广告的限制。您必须强制执行以下字段中的限制:

  • allowed_vendor_type
  • excluded_attribute
  • excluded_sensitive_category

一个字段指定允许使用的广告功能,另一个指定禁用的功能。切勿返回包含禁用功能的广告。对于允许的功能(例如供应商类型),仅当广告的供应商类型位于 BidRequestallowed_vendor_type 列表中时,才返回广告。如需了解详情,请参阅 BidRequest 协议缓冲区定义中针对这些字段的注释。

如果 BidResponse 中返回了 HTML 代码段,您必须在 BidResponse 中准确设置 attributecategoryclick_through_url 字段。如果广告的这些字段有多个适用的值,您必须添加每个值。如需了解详情,请参阅 BidResponse 协议缓冲区定义中这些字段的注释。未设置这些字段的响应会被舍弃。

BidRequest.excluded_attribute 可能的值如下(请参阅 publisher-excludable-creative-attributes.txt):

  • 7 Tagging: IsTagged
    如果广告中包含用于为后续再营销创建 Cookie ID 列表的像素或网络信标,就禁止投放。
  • 8 CookieTargeting: IsCookieTargeted
    如果广告是根据消费者的 Cookie ID 来定位消费者,其中 Cookie ID 列表表示之前曾与买家拥有或代表的网站进行过互动的一组消费者。
  • 9 UserInterestTargeting: IsUserInterestTargeted
    如果广告根据消费者的 Cookie ID 来定位消费者,则禁止投放广告,此处的 Cookie ID 列表表示被买家定义为常见兴趣群体的一组消费者。
  • 21 CreativeType: Html
    不允许广告使用 BidResponse.Ad 中的 html_snippetsnippet_template 字段。
  • 22 CreativeType: VastVideo
    不允许广告使用 BidResponse.Ad 中的 video_url 字段。
  • 30 InstreamVastVideoType: Vpaid
    不允许广告要求支持 VPAID 才能呈现。
  • 32 MraidType: MRAID
    不允许要求使用 MRAID API 才能呈现广告。
  • 34 RichMediaCapabilityType: RichMediaCapabilityFlash
    广告不得要求支持 Flash 才能呈现。
  • 39 RichMediaCapabilityType: RichMediaCapabilityHTML5
    不允许广告需要 HTML5 功能才能呈现。
  • 48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
    广告不得发出非 SSL 请求。

因此,如果 excluded_attribute 字段包含值 7,您不应返回使用像素或网络信标创建列表的广告。请注意,如果广告执行此操作,则必须在 BidResponse 的属性字段中设置值 7。同样,如果 excluded_attribute 字段包含值 48,则您应仅返回可在 SSL 页面上呈现的广告(并相应地声明属性 47 RichMediaCapabilityType: RichMediaCapabilitySSL)。

此外,BidRequest 中的 excluded_sensitive_category 字段使用引用数据页面上提供的 ad-sensitive-categories.txt 文件中的代码。以下是对其中一些代码的进一步说明:

  • 3 Politics
    包括政治问题或争议性的社会问题;不包括整体来说不涉及任何党派观点的新闻组织的广告。
  • 4 Dating
    包括约会服务和在线约会社区。
  • 5 Religion
    包括宗教广告以及倡导或反对宗教观点的广告;不包括占星术或非宗派精神类广告。
  • 7 Video Games (Casual & Online)
    包括视频游戏、在线游戏以及可下载的游戏;不包括视频游戏机。
  • 8 Ringtones & Downloadables
    铃声等手机内容以及其他可下载的内容,例如适用于台式机的屏保和壁纸以及适用于社交网络的个人资料布局和图片。
  • 10 Get Rich Quick
    承诺快速赚钱的方案。
  • 18 Weight Loss
    包括减肥、节食及相关产品和计划;不包括健康饮食或一般性健身广告。
  • 19 Cosmetic Procedures & Body Modification
    包括整容、吸脂、激光、脱毛、植发、文身和身体修形。
  • 23 Drugs & Supplements:
    包括医用药品、维生素、补充剂及相关零售商;不包括提供普通药品信息的资源。
  • 24 Sexual & Reproductive Health
    包括性功能和生殖类广告;不包括与怀孕相关的一般性资源。
  • 35 Social Casino Games
    包括没有机会赢得任何有价物品(例如现金或奖品)的模拟赌博游戏(包括但不限于:扑克、老虎机、宾果、彩票、体育博彩、比赛博彩以及其他纸牌游戏和赌场游戏)。
  • 36 Significant Skin Exposure
    广告图片中展示的是人体任何部位(从胸骨到大腿中部)均无衣物覆盖,或者全身仅穿了内衣、泳装、内衣或其他透明衣物或非衣物,例如毛巾或床单。
  • 37 Sensationalism
    广告通常采用包含夸张语言或图片的宣传语,通过激发用户的好奇心来吸引用户点击。包括以耸人听闻的主题(例如名人被捕、死亡或离婚)为主或旨在制造震惊效果的广告。

开放式衡量

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

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

出价响应示例

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

应用横幅广告

Google

OpenRTB JSON

OpenRTB 协议缓冲区

应用插页式广告

Google

OpenRTB JSON

OpenRTB 协议缓冲区

应用插页式视频广告

Google

OpenRTB 协议缓冲区

应用原生

Google

OpenRTB JSON

OpenRTB 协议缓冲区

网络视频

Google

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

OpenRTB 协议缓冲区