> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 素材规范

> 面向 CloudX 渲染（服务器到服务器）需求的素材类型、支持格式、单次竞价配置与行为

对于服务器到服务器（无 SDK）需求，CloudX SDK 直接从 `bid.adm` 标记在应用内渲染您的素材——不涉及任何网络 SDK。本页是渲染契约：说明接受哪些素材类型与格式、您可发送的单次竞价配置，以及 CloudX 强制执行的用户体验行为。

本规范仅适用于由 CloudX 渲染的竞价。渲染如何路由请参阅[需求合作伙伴概览](/zh/demand/overview)。

## 路由

当竞价响应携带 `ext.cloudx.render.provider = "cloudx"` 时，由 CloudX 渲染。CloudX 随后根据 `ext.crtype` 选择素材引擎：

| `ext.crtype`     | 渲染为              |
| ---------------- | ---------------- |
| `html`（或缺省）      | HTML / MRAID 3.0 |
| `vast` 或 `video` | VAST 视频          |

素材标记本身从 `bid.adm` 读取（HTML 文档或 VAST XML）。

## 素材类型

* **HTML / MRAID 3.0** — 静态与交互式 HTML 素材。向素材公开 MRAID 3.0 宿主 API。`mraid.useCustomClose()` 会被接受但无效果（参见[关闭控件](#关闭控件)）；在全屏广告位上，`expand()` 与 `resize()` 会被拒绝。
* **VAST 视频** — 支持 VAST 2.0 至 4.3。VAST 5.x 及无法识别的版本会以“版本不支持”错误安全失败，从而允许交易所投放兜底素材。不支持 VPAID。

## 支持的格式

| 格式             | HTML (MRAID 3.0) | VAST 视频 |
| -------------- | ---------------- | ------- |
| Banner（320×50） | ✓                | —       |
| MREC（300×250）  | ✓                | —       |
| 插屏             | ✓                | ✓       |
| 激励视频           | ✓                | ✓       |

CloudX 不渲染原生（Native）与开屏（App Open）。

## 单次竞价配置

可选的单素材行为通过 `ext.cloudx.render.player_config` 携带。所有字段均为可选；省略该块即采用 SDK 默认值。

```json theme={null}
{
  "ext": {
    "cloudx": {
      "render": {
        "provider": "cloudx",
        "player_config": {
          "close":  { "delay_seconds": 5 },
          "skip":   { "delay_seconds": 5 },
          "audio":  { "muted_by_default": false },
          "cta":    { "text": "Learn More" },
          "orientation": "auto"
        }
      }
    }
  }
}
```

| 字段                       | 类型      | 适用于      | 含义                                                |
| ------------------------ | ------- | -------- | ------------------------------------------------- |
| `close.delay_seconds`    | number  | 插屏、激励视频  | 关闭控件可见前的延迟。`0` = 立即可见。                            |
| `skip.delay_seconds`     | number  | 插屏（VAST） | 跳过控件出现前的播放时长。覆盖 VAST 的 `skipoffset`。              |
| `audio.muted_by_default` | boolean | VAST     | 视频播放是否以静音开始。默认不静音。                                |
| `cta.text`               | string  | 插屏、激励视频  | 行动号召按钮文案。缺省时回退为默认值。                               |
| `orientation`            | string  | 全屏       | `portrait`、`landscape` 或 `auto`。无法识别的值回退为 `auto`。 |
| `dec`                    | object  | 全屏       | 双结束卡配置，透传给结束卡渲染器。                                 |

**取值处理**

* 负数将被忽略并视为缺省（采用 SDK 默认值）。
* `0` 或缺省字段表示“采用 SDK 默认值”，绝非“立即”。例如，缺省 `close.delay_seconds` 会采用默认关闭延迟，而非显示立即关闭。
* 未知键会被容忍并忽略，因此新的服务端参数具有向前兼容性。

## 用户体验行为

CloudX 采用保守、非侵扰的默认体验，并且无论素材内容如何都强制执行关闭契约。

### 关闭控件

* 关闭控件由 SDK 绘制并拥有，位置固定在顶部尾侧安全区，点击区域不小于 50 pt。素材无法替换、隐藏或移动它。
* `mraid.useCustomClose()` 为兼容性而被接受，但为只观察的空操作——SDK 关闭控件始终存在。
* 发生卡顿时，看门狗会强制显示关闭控件，因此用户永远不会被困住。

### 插屏

关闭控件在 `close.delay_seconds`（默认 5 秒）后出现。对于 VAST，按 `skip.delay_seconds` 在跳过可用前显示倒计时；SDK 关闭控件始终作为兜底可用。

### 激励视频

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

<Warning>
  `close.delay_seconds` 默认为 5 秒，但**并非强制下限**。小于 5 秒的正值会按发送值生效。目前没有针对单次竞价时序的广告位级下限或过滤。
</Warning>

## 度量

* HTML 与 VAST 素材均支持 Open Measurement（OMID）可见性度量。
* 追踪 VAST 4.1 的 `ViewableImpression` 与标准 `Impression` 事件。
* 遵循 VAST 4.0+ 的 `AdVerifications`（OMID 验证资源）。

## 兜底行为

当素材无法渲染时——例如不支持的 VAST 版本、无法解析的负载或素材类型不匹配——CloudX 会安全失败并报告错误，从而允许交易所投放兜底素材，而不是展示损坏的广告。