竞价响应

CloudX 读取的 OpenRTB 竞价响应字段、广告标记规则，以及带宏的获胜/失败通知 URL。

如需对展示机会出价，请返回标准的 OpenRTB 竞价响应。本页介绍 CloudX 读取的字段、CloudX 渲染素材的标记规则，以及用于跟踪结果的通知 URL。

不参与竞价的响应

要放弃某次展示，请返回 HTTP 204（响应体为空）或 HTTP 200（seatbid 数组为空）。当您想在 nbr（OpenRTB 列表 5.24）中说明原因时使用 200 形式——204 无法携带响应体。

响应对象

字段	类型	要求	说明
`id`	string	必需	您所响应的竞价请求的 `id`。
`seatbid`	object array	必需	每个响应发送一个 seat、一条出价。
`seatbid[].seat`	string	可选	响应中的 seat ID。通知交付使用 CloudX 配置的竞价方或适配器身份来标识 seat，并不直接读取此字段。
`cur`	string	可选	`"USD"`，或省略（默认为 USD）。其他货币会被拒绝。
`bidid`	string	可选	用于对账的响应 ID。保留了响应级上下文的路径会将其用于 `${AUCTION_BID_ID}`；否则该宏回退为 `bid.id`。
`nbr`	integer	可选	OpenRTB 不参与竞价原因（列表 5.24）。在 HTTP `200` 响应中与空 `seatbid` 数组一起使用。

Bid 对象

字段	类型	要求	说明
`id`	string	必需	您为本次出价生成的唯一 ID。
`impid`	string	必需	您所出价的 `imp` 的 `id`。
`price`	float	必需	必须为正数的美元 CPM 出价。第一价格：获胜后按此金额支付。您的 `price` 必须达到请求中发送的 `imp.bidfloor`；请按竞价方 CPM 口径提交，不要自行应用 CloudX 配置的调整。CloudX 会让这些调整与内部竞价底价在底价校验和排名时保持等价口径。
`adm`	string	必需	广告素材标记——HTML/MRAID 片段或 VAST XML 文档。CloudX 直接渲染；请参阅下文标记规则和广告素材规范。
`crid`	string	必需	稳定的素材 ID。同一素材每次都应使用相同值，以便 CloudX 持续识别、调查和屏蔽。
`adid`	string	可选	待展示广告标记的 ID。部分通知路径会为 `${AUCTION_AD_ID}` 保留该值；基于展示事件的路径则使用素材 ID。
`adomain`	string array	必需	至少一个非空广告主域名，不含协议或路径。CloudX 会将可注册域名与请求中的 `badv` 屏蔽列表比较。
`cat`	string array	必需	使用 IAB Content Taxonomy 1.0 类别准确描述实际投放的素材和落地页内容。不得使用更宽泛或无关的类别。参阅信任与供应质量。
`bundle`	string	条件必需	广告推广应用时必填。使用广告推广应用的 Android 包名或数字 iOS App Store ID，而非展示广告的应用的 `app.bundle`。CloudX 会将其与请求中的 `bapp` 和发布商配置的应用屏蔽项比较。
`cattax`	integer	可选	OpenRTB 2.6 中用于 `cat` 的类别分类法。对于 IAB Content Taxonomy 1.0 类别，使用 `1` 或省略该字段；省略时默认为 `1`。
`nurl`	string	建议	获胜通知 URL，见获胜和失败通知。
`burl`	string	建议	计费通知 URL。请在此跟踪展示和支出。
`lurl`	string	建议	失败通知 URL，携带失败原因代码。
`ext.crtype`	string	条件必需	素材类型标签。CloudX 按不区分大小写的方式归一化：`html`、`mraid`、`static` 映射为 `html`；`vast`、`video` 映射为 `vast`。仅当媒体类型明确时才可省略。对于以 `banner` 形态发送的 App Open 或插屏请求，如返回 VAST，必须设置为 `"vast"`；OpenRTB 2.6 还应设置 `mtype: 2`。

广告标记规则

遵守请求中的 bcat、badv、bapp 及任何 battr 素材属性屏蔽。遵守 bcat 和 bapp 是 CloudX OpenRTB 集成要求；需求合作伙伴策略要求遵守 badv 和 battr。出价被接受并不免除这些要求。
请在 adm 中返回完整标记。CloudX 不会从 nurl 获取标记。
所有 URL 必须使用 HTTPS。 HTTP 引用违反合作方契约，并可能被拒绝。
HTML/MRAID 标记是由 CloudX SDK 在 WebView 中渲染的片段；VAST 标记是完整的 XML 文档。格式、尺寸和渲染行为请参阅广告素材规范。

获胜和失败通知

CloudX 会随着竞价结果和设备端结果的确定，调用您出价中的相应通知 URL：

字段	触发时机
`nurl`	获胜通知。旧版 SDK 流量在广告加载后触发；当前基于展示事件的 SDK 流量在记录已渲染展示时触发。
`burl`	获胜广告完成渲染并达到计费条件时。请在此跟踪展示和支出。
`lurl`	您的出价未获胜或被拒绝时，包括出价获胜但广告加载或渲染失败的情况。

通知采用异步、尽力而为方式交付，并非恰好一次。通知可能延迟、重试、重复、乱序或丢失。处理程序应具备幂等性：按 URL 类型以及 ${AUCTION_ID}、${AUCTION_IMP_ID} 和 ${AUCTION_BID_ID} 去重，并仅在持久记录事件后返回 2xx。

宏

您可以在通知 URL 中嵌入宏，CloudX 会在调用前替换为实际值。宏区分大小写，请始终使用 ${...} 形式。

宏	替换值
`${AUCTION_PRICE}`	取决于结果的价格；货币、单位和竞价方 CPM 口径与您的出价一致。详见下表。
`${AUCTION_MIN_TO_WIN}`	取决于结果的最低价格或底价。详见下表。也接受别名 `${AUCTION_MINIMUM_BID_TO_WIN}` 和 `${AUCTION_BID_TO_WIN}`。
`${AUCTION_LOSS}`	OpenRTB 失败原因代码，仅用于 `lurl`，见下表。
`${AUCTION_ID}`	竞价请求的 `id`。
`${AUCTION_BID_ID}`	通知路径保留的响应 `bidid`；否则为 `bid.id`。
`${AUCTION_IMP_ID}`	展示的 `id`。
`${AUCTION_SEAT_ID}`	CloudX 为该出价配置的竞价方或适配器 seat。
`${AUCTION_AD_ID}`	路径保留的 `bid.adid`；基于展示事件的路径则使用素材 ID。两者都不可用时可能为空。
`${AUCTION_CURRENCY}`	出价货币（`USD`）。
`${AUCTION_MBR}`	两个值都可用时，`${AUCTION_PRICE}` 除以收到通知的出价价格。

当某条通知路径未提供宏所需的上下文时，该宏会以原文保留，例如 nurl 中的 ${AUCTION_LOSS}。如果该路径提供了上下文，但可选来源字段为空，替换结果可能为空值。请确保处理程序能够同时容忍字面宏文本和空值。

价格宏行为

通知结果	`${AUCTION_PRICE}`	`${AUCTION_MIN_TO_WIN}`
获胜 `nurl` 或 `burl`	获胜出价的 CPM；CloudX 采用第一价格竞价。	获胜方底价与下一名出价加 0.01 美元两者中的较大值，且最低为 0.01 美元。
`lurl`，代码 `1`	`0`	`0`
`lurl`，代码 `2` 或 `3`	当该失败路径提供价格上下文时为 `0`。	不提供；宏保持原文。
`lurl`，代码 `100` 或 `101`	拒绝该出价的底价。	同一底价。
`lurl`，代码 `102`	当前基于展示事件的路径使用按收到通知的竞价方 CPM 口径表示的获胜竞价价格。没有费用口径的旧版通知路径可能使用收到通知的出价自身 CPM。	与 `${AUCTION_PRICE}` 相同。

失败原因代码

${AUCTION_LOSS} 携带以下 OpenRTB 代码之一：

超时响应会被丢弃。不要依赖超时响应中的 lurl 收到代码 2；服务器生成的超时通知仅适用于实现该能力的特定端点适配器。

代码	含义	常见原因
`1`	内部错误	CloudX 处理您的出价时发生意外故障，或您的获胜出价广告在设备端加载或渲染失败。
`2`	已过期	由特定端点适配器生成的服务器超时通知。
`3`	无效的竞价响应	运行时校验所检查的字段缺失或格式错误，或标记未通过校验。
`6`	无效的广告主域名	声明的 `adomain` 与请求中的 `badv` 广告主屏蔽列表匹配。
`100`	低于竞价底价	`price` 低于 `imp.bidfloor`。
`101`	低于 deal 底价	`price` 低于您所出价的 deal 的底价。
`102`	输给更高出价	出价有效，但在该轮中被更高出价击败。
`200`	素材被过滤	素材 ID（`crid`）或广告活动 ID（`cid`）与发布商配置的屏蔽项匹配。
`209`	类别屏蔽	声明的 `cat` 与请求中的 `bcat` 类别屏蔽列表匹配。
`210`	素材属性屏蔽	声明的 `attr` 与发布商配置的素材属性屏蔽项匹配。
`215`	应用标识符屏蔽	广告推广应用的 `bundle` 与请求中的 `bapp` 或发布商配置的应用屏蔽项匹配。

响应示例

{
  "id": "7f3d9a1c2e4b48f0a6d5c8b2e1f40937",
  "cur": "USD",
  "bidid": "b-92f4ac",
  "seatbid": [
    {
      "seat": "your-seat-id",
      "bid": [
        {
          "id": "bid-0001",
          "impid": "1",
          "price": 6.25,
          "crid": "creative-48291",
          "adid": "ad-48291",
          "adomain": ["advertiser.example"],
          "cat": ["IAB1-1"],
          "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"3.0\">...</VAST>",
          "nurl": "https://events.bidder.example/win?price=${AUCTION_PRICE}",
          "burl": "https://events.bidder.example/bill?price=${AUCTION_PRICE}",
          "lurl": "https://events.bidder.example/loss?reason=${AUCTION_LOSS}&price=${AUCTION_PRICE}",
          "ext": { "crtype": "vast" }
        }
      ]
    }
  ]
}

下一步：广告素材规范

CloudX 渲染需求的素材类型、尺寸和渲染行为。