素材规范

面向 CloudX 渲染（服务器到服务器）需求的素材类型、支持格式与渲染行为

对于服务器到服务器（无 SDK）需求，CloudX 直接从 bid.adm 标记在应用内渲染您的素材——不涉及任何网络 SDK。本页说明 CloudX 接受的素材类型与格式，以及其应用的用户体验行为。

竞价响应

在标准 OpenRTB bid.adm 字段中返回素材标记。当请求形态无法明确判断媒体类型时，必须在 bid.ext.crtype 中声明素材类型（html、mraid 或 vast）。特别是，以 banner 形态发送的 App Open 或插屏请求如返回 VAST，必须设置 crtype: "vast"；OpenRTB 2.6 响应还应设置 bid.mtype: 2。

{
  "id": "<竞价请求中的 id>",
  "seatbid": [
    {
      "bid": [
        {
          "id": "1",
          "impid": "<竞价请求中的 imp id>",
          "price": 2.50,
          "crid": "creative-123",
          "adomain": ["advertiser.example"],
          "adm": "<!doctype html> …（HTML/MRAID 文档，或 VAST XML）",
          "ext": { "crtype": "html" }
        }
      ]
    }
  ]
}

adm 中的素材必须满足以下要求。除 ext.cloudx.render.auto_store 和 ext.cloudx.render.player_config.cards（见转化界面）外，请勿发送其他 ext.cloudx.* 字段；CloudX 会在竞价后填充渲染路由。

素材类型

HTML / MRAID 3.0 — 静态与交互式 HTML 素材。MRAID 能力因平台而异：Android 不支持 expand、resize 或 playVideo；iOS 支持 playVideo 以及内嵌场景的 expand/resize，但不支持全屏展开或缩放。两个平台都不会执行 useCustomClose。
VAST 视频 — 支持 VAST 2.0 至 4.3。VAST 5.x 及无法识别的版本会以“版本不支持”错误导致渲染失败。不支持 VPAID。

支持的格式

格式	HTML (MRAID 3.0)	VAST 视频
Banner（320×50）	✓	—
MREC（300×250）	✓	—
插屏	✓	✓
激励视频	✓	✓
原生广告	—	—
开屏广告（App Open）	视端点配置而定	视端点配置而定

对于符合条件的端点配置，App Open 使用与插屏相同的全屏渲染器，并接受 HTML/MRAID 或 VAST 素材。CloudX 会在接入期间确认支持情况。

面向发布商的广告格式目录中的原生广告通过移动 SDK 网络适配器提供。原生广告不在本页所述的公开 OpenRTB 买方端点约定范围内；任何单独的原生广告端点集成都必须由 CloudX 确认。

用户体验行为

CloudX 由 SDK 管理可见的全屏关闭控件。素材仍可调用 mraid.close() 立即关闭插屏广告，或在满足奖励资格后关闭激励广告。如果服务器配置未覆盖，VAST 素材的 skipoffset 可影响跳过时间或观看达标时间。

关闭控件

关闭控件由 SDK 绘制并拥有，位置固定在顶部尾侧安全区；最小点击区域在 Android 上为 50 dp，在 iOS 上为 50 pt。素材无法替换、隐藏或移动它。
mraid.useCustomClose() 为兼容性而被接受，但为只观察的空操作——SDK 拥有的关闭控件始终具有决定权。
SDK 管理的计时器和渲染状态决定控件何时显示。VAST 包含在卡顿时显示关闭控件的逃生机制。MRAID 卡顿状态看门狗只上报遥测；它们不会显示控件或终止广告。

插屏

对于 HTML/MRAID，CloudX 关闭控件通常在 5 秒后出现。VAST 插屏的跳过倒计时取决于服务器配置、素材 skipoffset 或默认 5 秒；关闭控件主要在播放完成、结束卡阶段或较晚的卡顿保护时出现。

激励视频

激励视频广告位默认不可跳过，且不提供跳过控件；用户观看至完成。
若适用观看得奖阈值，越过阈值后会出现关闭控件（而非跳过控件）。服务器未覆盖时，VAST skipoffset 可定义该阈值。此后用户退出仍保留奖励。
奖励在完成时发放，或在满足资格后退出时发放。卡顿期间的应急退出不发放奖励。
观看得奖资格仅按前台时间累计；将应用切换到后台不会推进计时。

转化界面

在 iOS 上，CloudX 通过三种界面缩短 VAST 插屏或激励视频广告到安装的路径：

App Store 页面（AutoStore）：视频结束时，在第一张结束卡之前，于应用内打开所推广应用的产品页面。如果广告没有结束卡，则在用户关闭广告时打开，并在页面关闭后再关闭广告。每个广告最多展示一次。
SKOverlay：Apple 的 App Store 横幅。当广告同时使用 AutoStore 时，横幅会在 App Store 页面关闭后出现，并默认在广告剩余时间内保持显示。广告关闭时横幅始终会被移除。
结束卡序列：先展示 VAST 伴随素材（如有），再依次展示您在 cards 中发送的卡片。每张卡片都有自己的安装按钮和关闭控件。

App Store 页面和 SKOverlay 会携带您竞价中已签名的 SKAdNetwork 数据，因此由它们带来的安装可获得 StoreKit 渲染（fidelity: 1）归因。所需字段见 SKAdNetwork。转化界面需要 CloudX iOS SDK 3.10 或更高版本。

默认行为

当以下条件全部满足时，CloudX 会为竞价添加 AutoStore 和 SKOverlay：

请求来自 CloudX iOS SDK 3.10 或更高版本；
广告位为插屏或激励视频（不包括 App Open）；
素材为 VAST；
竞价包含 bid.ext.skadn.itunesitem。

字段	CloudX 添加的默认值
`bid.ext.cloudx.render.auto_store`	`{"enabled": true, "on_skip": true, "on_close": true}`
`bid.ext.skadn.skoverlay`	`{"pos": 0, "dismissible": 0, "delay": 0, "endcarddelay": 0}`

CloudX 只补充您竞价中缺少的字段。您发送的字段会按原样使用，包括选择退出。

可设置的字段

bid.ext.cloudx.render.auto_store

键	类型	含义
`enabled`	boolean	`false` 表示此竞价关闭 AutoStore。
`on_skip`	boolean	用户跳过视频时打开 App Store 页面。
`on_close`	boolean	在第一张结束卡之前打开 App Store 页面；如果没有结束卡，则在广告关闭时打开。

如需选择退出，请发送 "auto_store": {"enabled": false}。

bid.ext.skadn.skoverlay（字段名来自 IAB SKAdNetwork 扩展）

键	类型	含义
`pos`	integer	`0` 底部，`1` 底部抬高。其他值按底部处理。
`dismissible`	integer	`1` 用户可以滑动关闭，`0` 不可关闭。如果发送 `skoverlay` 但不含此键，横幅可关闭。
`delay`	number	视频开始后多少秒显示横幅。`-1` 或缺省表示禁用此阶段。
`endcarddelay`	number	结束卡开始后多少秒显示横幅。`-1` 或缺省表示禁用此阶段。
`ext.sk_dismiss_delay`	number	横幅显示后多少秒自动移除。`-1` 或缺省表示保持显示。

当竞价同时使用 AutoStore 时，横幅会等到 App Store 页面关闭后才显示。如需选择退出横幅，请发送 "skoverlay": {"delay": -1, "endcarddelay": -1}。

bid.ext.cloudx.render.player_config.cards

结束卡数组，在 VAST 伴随素材之后按顺序展示。每张卡片：

键	类型	含义
`app_name`	string	卡片上显示的应用名称。
`app_icon_url`	string	应用图标图片 URL。
`cta_text`	string	安装按钮文字。
`click_through`	string	安装按钮的跳转地址。App Store 链接会打开应用内产品页面。
`close.delay_seconds`	number	卡片关闭控件出现前的秒数，上限为 5。最后一张卡片的关闭控件不会早于 2 秒出现。

没有可渲染内容的卡片会被跳过。当 cards 缺省时，仍会读取单卡片的 player_config.dec 对象。

其他所有 ext.cloudx.* 字段仍由 CloudX 设置。

示例

{
  "id": "1",
  "impid": "<竞价请求中的 imp id>",
  "price": 8.00,
  "adm": "<VAST version=\"4.2\"> … </VAST>",
  "ext": {
    "crtype": "vast",
    "skadn": {
      "version": "4.0",
      "network": "example.skadnetwork",
      "itunesitem": "1234567890",
      "sourceapp": "987654321",
      "campaign": "12",
      "fidelities": [
        { "fidelity": 1, "nonce": "…", "timestamp": "…", "signature": "…" }
      ],
      "skoverlay": { "pos": 0, "dismissible": 1, "endcarddelay": 0 }
    },
    "cloudx": {
      "render": {
        "auto_store": { "enabled": true, "on_skip": true, "on_close": false },
        "player_config": {
          "cards": [
            { "app_name": "Example Game", "app_icon_url": "https://cdn.example.com/icon.png", "cta_text": "Install", "click_through": "https://apps.apple.com/app/id1234567890" },
            { "app_name": "Example Game", "cta_text": "Play free", "click_through": "https://apps.apple.com/app/id1234567890" }
          ]
        }
      }
    }
  }
}

资源限制

全屏 adm：8 MiB
每个 VAST XML 文档或 Wrapper 响应：2 MiB
VAST 媒体文件：50 MiB
Wrapper 深度：5

跨平台兼容素材应使用 video/mp4；其他已声明的 MIME 类型需确认端点与渲染器支持。

度量

SDK 会尝试为 HTML 和 VAST 素材创建 Open Measurement（OMID）会话；该过程属于尽力而为，认证一致性取决于已发布的 SDK 版本。
在相应路径可用时，追踪 VAST 4.1 的 ViewableImpression 与标准 Impression 事件。
有效的 VAST 4.0+ AdVerifications 资源用于尝试启动供应商度量。

兜底行为

当素材无法渲染时——例如不支持的 VAST 版本、无法解析的负载或素材类型不匹配——CloudX 会使渲染失败。对于 bid.ext.crtype 无法识别的出价，SDK 可能在渲染前跳过该出价，而不会自动向买方发送错误或竞价失败通知。CloudX 不保证从同一次竞价中再提供其他素材。