> ## 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.

# 管理广告单元

> 广告单元代表应用中展示广告的具体位置。

<img src="https://mintcdn.com/cloudx-928dcb24/dvzjl4I9j7cnSnQy/images/ad-units-zh.png?fit=max&auto=format&n=dvzjl4I9j7cnSnQy&q=85&s=71fc5a304e6dc65faec3e1c8b5e951ee" alt="管理广告单元" width="2608" height="1184" data-path="images/ad-units-zh.png" />

# 创建广告单元

您可以从侧边栏的广告单元页面或直接从应用页面创建广告单元。从应用页面创建时，系统会自动为您预选该应用。

创建广告单元：

1. 点击 **+ 添加广告单元**
2. 为广告单元命名，名称须与 SDK 代码中的名称完全一致
3. 选择该广告单元所属的应用（如尚未选择）
4. 选择广告格式
5. 配置特定格式的设置
6. 点击**保存**

<video controls width="100%" playsInline alt="演示如何在 CloudX 控制台中创建新的广告单元并配置相关设置的视频。">
  <source src="https://mintcdn.com/cloudx-928dcb24/dvzjl4I9j7cnSnQy/en/files/add-ad-unit-zh.mp4?fit=max&auto=format&n=dvzjl4I9j7cnSnQy&q=85&s=802ba0cafc40222956f4c85eeb3b20ad" type="video/mp4" data-path="en/files/add-ad-unit-zh.mp4" />
</video>

# 广告格式

| 格式     | 尺寸      | 说明                          |
| ------ | ------- | --------------------------- |
| 横幅广告   | 320x50  | 支持自动刷新的标准横幅广告               |
| MREC   | 300x250 | 适用于内容信息流的中等矩形广告             |
| 插屏广告   | 全屏      | 在自然过渡时展示的全屏广告               |
| 激励视频广告 | 全屏      | 用户观看后可获得奖励的视频广告（如额外生命、游戏货币） |

# 广告格式设置

**1. 横幅广告、MREC：**

<img src="https://mintcdn.com/cloudx-928dcb24/dvzjl4I9j7cnSnQy/images/banner-zh.png?fit=max&auto=format&n=dvzjl4I9j7cnSnQy&q=85&s=ddbfe754625c6f26670a8030eb647d39" alt="横幅广告、MREC" width="1538" height="578" data-path="images/banner-zh.png" />

刷新率 - 横幅广告的刷新间隔，以秒为单位。常用值为 30、60 或 90 秒。设置为 0 可禁用自动刷新。

**2. 激励视频广告：**

<img src="https://mintcdn.com/cloudx-928dcb24/dvzjl4I9j7cnSnQy/images/rewarded-zh.png?fit=max&auto=format&n=dvzjl4I9j7cnSnQy&q=85&s=f949a322e0e3dc68daf0c3bb1c5ca75e" alt="激励视频广告" width="1480" height="672" data-path="images/rewarded-zh.png" />

* **奖励金额** - 用户观看广告后获得的物品数量。例如，10 枚金币或 1 条额外生命。

* **奖励货币** - 奖励的名称。例如，金币、宝石或额外生命。

* **奖励回调 URL** - 服务器到服务器的回调 URL，当用户完成激励视频广告后，CloudX 会调用此 URL。在向用户发放奖励前，可使用此功能在您的后端验证奖励。详见[激励回调](#激励回调)。

# 频次控制

您可以使用频次控制来限制同一用户在指定时间窗口内看到某个广告单元的展示次数。

CloudX 当前支持以下广告单元频次窗口：

* `hour`
* `day`
* `session`

## 配置广告单元频次上限

1. 打开**广告单元**
2. 选择要更新的广告单元
3. 在**频次控制**区域启用该功能
4. 设置**最大展示次数**
5. 选择**时间窗口**
6. 点击**保存更改**

示例：

* `2 / hour` 表示同一用户在一个小时内最多只能看到该广告单元的 2 次展示

## 生效方式

频次控制会在竞价前检查，但会在展示成功后才计数。

这意味着：

* 仅仅发起一次请求或完成一次竞价**不会**消耗频次
* 只有广告真正展示后，计数器才会增加
* 当用户达到上限后，受限库存会返回 **no fill**

## 说明

* 会话级频次控制要求 SDK 在广告请求中发送 session ID。
* 广告单元频次控制与分群频次控制是独立校验的。如果两者都已配置，请求必须同时通过两种检查才会投放。
* 控制台中的**分群**页面也支持为分群流量以及未分群流量的默认流量配置频次控制。

# 激励回调

当用户完成激励广告后，CloudX 会向您配置的回调 URL 发送 HTTP GET 请求。您可以在服务器端验证奖励后再向用户发放。

在**奖励回调 URL** 字段中，粘贴包含以下宏的 URL。CloudX 在发送请求前会将每个宏替换为实际值。

示例：

```
https://your-server.com/rewards?event_id={EVENT_ID}&token={EVENT_TOKEN}&amount={AMOUNT}&currency={CURRENCY}&data={CUSTOM_DATA}&revenue={REVENUE}
```

## 支持的宏

| 宏               | 描述                                     | URL 编码 |
| --------------- | -------------------------------------- | ------ |
| `{EVENT_ID}`    | 奖励事件的唯一标识符。                            | 否      |
| `{EVENT_TOKEN}` | 基于 Event ID 生成的验证令牌，可用于服务端回调验证。        | 否      |
| `{AMOUNT}`      | 广告单元上配置的奖励数量（数字）。始终存在，默认为 `0`。         | 否      |
| `{CURRENCY}`    | 广告单元上配置的奖励货币名称。                        | 是      |
| `{CUSTOM_DATA}` | SDK 传递的自定义字符串。可用于将游戏关卡或用户状态等上下文附加到回调中。 | 是      |
| `{REVENUE}`     | 单次展示收入值（数字）。如不可用，默认为 `0`。              | 否      |

标记为 **URL 编码**的宏会进行百分号编码，确保可安全用作查询参数值。如果宏的值未设置，将替换为空字符串——占位符不会被原样发送。

## 重试行为

如果您的服务器超时，CloudX 最多重试 **2 次**。非超时错误（4xx、5xx）不会重试。请确保您的端点在几秒内响应。

# 创建广告单元后

广告单元创建完成后：

1. 在 SDK 代码中使用**完全相同的广告单元名称**进行引用
2. **创建行项目**，定义哪些需求来源投放广告及其出价
3. **配置网络映射**，将广告单元与需求合作伙伴连接