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

# 标签

> 通过为每次广告请求附带一个或多个标签值，将请求路由到特定的广告项。可用于自有广告（house ad）、兜底库存、A/B 受众切分等任意请求级别的路由规则。

# 介绍

标签允许您将一次广告请求路由到指定的广告项子集。SDK 会为广告请求附带一个标签数组，只有配置了匹配标签的广告项才会参与该次展示的竞价。

典型使用场景是为自有广告或兜底活动保留库存：

* SDK 为请求标记 `tags = ["house_ad"]`
* 只有配置了 **house\_ad** 标签的广告项进入竞价
* 即使其他广告项优先级更高，也会在该次请求中被跳过

每次请求可以携带一个或多个标签。广告项也可以配置多个标签，只要请求标签与广告项标签存在任意匹配，广告项就有资格参与竞价。

# 匹配规则

CloudX 在带标签流量和不带标签流量之间实施严格隔离。请求中是否包含标签完全决定了哪些广告项可参与竞价。

| 请求标签 | 广告项标签     | 结果  |
| ---- | --------- | --- |
| 空    | 空         | 可参与 |
| 空    | 非空        | 跳过  |
| 非空   | 空         | 跳过  |
| 非空   | 非空，任一标签匹配 | 可参与 |
| 非空   | 非空，无匹配标签  | 跳过  |

<Warning>
  两个池之间没有回退机制。如果 SDK 发送的标签没有对应的广告项配置，请求将无可参与的广告项，也不会运行竞价。请务必先创建好广告项，再在 App 中启用对应的标签。
</Warning>

# 创建或编辑带标签的广告项

标签配置位于广告项表单的\*\*高级（可选）\*\*步骤内。

1. 打开**广告项**并点击 **+ 添加广告项**，或编辑现有广告项
2. 按常规流程完成**常规**和**定向**配置
3. 展开**高级（可选）**
4. 在**标签**区域，点击任一标签即可选中或取消选中
5. 如需新增标签，点击 **+ 创建新标签**，输入名称（例如 `Catch All`），然后点击**添加**
6. 点击**保存**

<img src="https://mintcdn.com/cloudx-928dcb24/tjShSaYLyn9doZNe/images/tags.png?fit=max&auto=format&n=tjShSaYLyn9doZNe&q=85&s=7460510092b139448787fae0cc2e09a9" alt="标签" width="2376" height="1492" data-path="images/tags.png" />

<Info>
  **未选择**任何标签的广告项只会服务**未携带**标签的请求。选择了一个或多个标签的广告项只会服务 `tags` 数组中至少有一个值匹配的请求。
</Info>

<Tip>
  标签名称在保存时会被转换为 slug 形式（`Catch All` 会变成 `catch_all`）。请在 SDK 代码中使用 slug 名称。
</Tip>

# 从 SDK 发送标签

在调用 `load` 前，在广告对象上调用 `setExtraParameter` 附加标签数组。您可以在多次加载之间更改这些值——SDK 会在调用 `load` 时捕获当时的值，后续修改将在下一次 `load` 时生效。

<Note>
  **SDK 最低版本要求**

  * **Android** — `setExtraParameter` 自 **Android SDK 3.2.0** 起可用
  * **iOS** — `setExtraParameter` 自 **iOS SDK 3.4.0** 起可用

  更早的 SDK 版本不会发送请求标签，仅会从未配置标签的广告项中获取广告。
</Note>

## Android

`setExtraParameter` 在横幅（`CloudXAdView`）、插屏与激励视频（`CloudXFullscreenAd`）以及原生广告（`CloudXNativeAdLoader`）上均可使用。

**Kotlin:**

```kotlin theme={null}
// 横幅 / MREC
adView.setExtraParameter("tags", listOf("house_ad"))
adView.load()

// 插屏
interstitial.setExtraParameter("tags", listOf("vip", "house_ad"))
interstitial.load()

// 原生
nativeAdLoader.setExtraParameter("tags", listOf("house_ad"))
nativeAdLoader.loadAd()
```

**Java:**

```java theme={null}
adView.setExtraParameter("tags", Arrays.asList("vip", "house_ad"));
adView.load();
```

如需在后续加载中停止发送标签，传入 `null`：

```kotlin theme={null}
adView.setExtraParameter("tags", null)
```

## iOS

`setExtraParameter` 在横幅（`CLXBannerAdView`、`CLXBanner`）、全屏广告（`CLXFullscreenAd`）以及原生广告（`CLXNativeAdLoader`）上均可使用。

**Swift:**

```swift theme={null}
// 横幅 / MREC
banner?.setExtraParameter("tags", value: ["house_ad"])
banner?.load()

// 插屏 / 激励
interstitial?.setExtraParameter("tags", value: ["vip", "house_ad"])
interstitial?.load()

// 原生
nativeLoader?.setExtraParameter("tags", value: ["house_ad"])
nativeLoader?.load()
```

**Objective-C:**

```objc theme={null}
[self.banner setExtraParameter:@"tags" value:@[@"vip", @"house_ad"]];
[self.banner load];
```

如需在后续加载中停止发送标签，传入 `nil` / `null`：

```swift theme={null}
banner?.setExtraParameter("tags", value: nil)
```

# 验证配置

在 SDK 集成和广告项保存完成后，请在投入生产前确认端到端的链路：

1. 在控制台中将该广告项的状态设为**已激活**
2. 在 App 构建中，在 `load` 之前调用 `setExtraParameter("tags", ["..."])`
3. 触发一次广告请求，确认展示由预期的广告项提供

<Warning>
  如果 SDK 开始发送没有任何已激活广告项配置的标签，这些请求将不会进入竞价。CloudX 会在服务端日志中输出告警——请协调好广告项变更与 SDK 发版顺序，确保广告项先于 SDK 上线。
</Warning>

# 常见模式

**自有广告 / 兜底库存。** 创建一条带有 **house\_ad** 标签的广告项，并让 App 在希望投放自有素材时发送 `tags = ["house_ad"]`。其他请求仍走常规的变现池。

**受众分组。** 在 App 代码中为 VIP 或高 LTV 用户打上 `tags = ["vip"]`，并将高价值广告项配置为带有 **vip** 标签，从而专门服务这些用户。

**组合路由。** 当一次请求需要匹配带有任一标签的广告项时，可以发送多个值，例如 `tags = ["vip", "house_ad"]`。