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

# ID 与 token

> publisherToken、placement code、userId、conversationId、IFA、IDFV——每一个是什么、由谁生成、用来做什么。

每一次 Kontext 接入都涉及若干个标识符。其中一些由你在创建会话时传入；一些由 Kontext 在 onboarding 时发放；还有一些由 SDK 直接从操作系统读取。本页解释每一个的含义、生成方与用途。

| 标识符              | 由谁生成                    | 作用范围                | 用途                                      |
| ---------------- | ----------------------- | ------------------- | --------------------------------------- |
| `publisherToken` | Kontext，在 onboarding 时  | 你的账号                | 标识请求归属于哪个发布方账号。                         |
| Placement `code` | Kontext，在 onboarding 时  | 每种广告位类型             | 标识组件代表哪一类广告位（默认是 `inlineAd`）。           |
| `userId`         | 你                       | 每个用户，跨对话保持不变        | 让广告服务在不同对话中识别同一用户——对再营销、奖励广告、频次控制都是必需的。 |
| `conversationId` | 你                       | 每次对话                | 在我们的分析与链路上标识一次具体的对话。                    |
| IFA（IDFA / GAID） | Apple / Google，由 SDK 读取 | 每台设备，需用户授权          | 平台标准的广告标识符；在可用时用于再营销和频次控制。              |
| IDFV             | Apple，由 SDK 读取          | 同一开发者在 iOS 设备上的所有应用 | iOS 专属的稳定标识符，无需 ATT；与 IFA 配合使用。         |

## `publisherToken`

Kontext 在 onboarding 时为你发放 `publisherToken`。它标识你的账号、决定你的应用能渲染哪些广告位与广告形式，并且是广告服务用来归属收入的关键。

通常你会拿到**两个 token**：

* **开发 token**：返回测试广告（标准测试素材，适合接入期间端到端验证）。
* **生产 token**：参与真实竞价。

你可以把生产 token 打包进客户端应用——它不是服务端密钥。把它当作一个权限范围有限的"公开 API key"：不要主动公开，但即使在客户端二进制里被人拿到，也不构成安全事件。

## Placement `code`

**Placement code** 用于标识应用中某种具体的广告位。默认值是 `inlineAd`，多数应用直接使用即可，无需额外配置。如果你的应用使用了多种广告位，Kontext 会在 onboarding 时发放额外的 code。

每个广告组件都需要传入对应的 placement code（例如 `<InlineAd code="inlineAd" messageId="..." />`）。如果你的应用使用自定义或多个 placement code，创建会话时还需在 `enabledPlacementCodes` 中传入允许渲染的 code 列表——SDK 只会尝试填充出现在该列表中的 placement。

## `userId`

`userId` 是**你**自己定义的用户标识。它应当满足：

* **跨对话保持稳定。** 同一用户明天再开一个新对话，`userId` 必须不变。这是再营销与奖励广告能工作的基础——广告服务需要知道自己正在跟之前见过的同一个用户对话。
* **不要使用个人身份信息（PII）。** 传入你内部的匿名用户 ID。广告服务不需要 PII 就能完成工作。
* **每个用户唯一。** 不同用户必须使用不同的 `userId`——`"anonymous"`、`null`、空字符串等"匿名兜底值"会把所有用户折叠成一条记录，毁掉再营销。

如果你的应用还没有稳定的用户 ID，可以在首次启动时生成一个 UUID 并持久化，这就够用了。

## `conversationId`

`conversationId` 是**你**为这次对话定义的标识。每当用户开启一个新对话时生成一个新的 `conversationId`，并在整段对话内持续复用。会话与 `conversationId` 一一绑定——具体的复用与重建规则见 [会话生命周期](/concepts/session)。

`conversationId` 在同一用户的所有对话中应当唯一。复用会把无关对话的广告缓存与分析数据混在一起——SDK 仍能继续工作，但数据将不可信。

## 广告标识符（IFA）

当平台原生的 **Identifier for Advertisers** 可用且用户授权时，SDK 会自动读取：

* **iOS —— IDFA。** iOS 14 起需要通过 Apple 的 App Tracking Transparency（ATT）弹窗授权。你的应用必须在 `Info.plist` 中声明 `NSUserTrackingUsageDescription`，并在自然的时机触发授权弹窗。
* **Android —— GAID。** SDK 会通过 manifest merger 自动声明 `com.google.android.gms.permission.AD_ID` 权限，并受用户 Google 账号广告个性化设置的影响。
* **Web。** 无直接对应物。

你不需要传入 IFA——SDK 会直接从操作系统读取。IFA 可用时，每次广告请求都会携带；不可用时（用户拒绝授权、系统级 opt-out，或该平台没有 IFA），SDK 会回退到一个内部生成的第一方标识符。同意与平台政策细节见 [合规](/resources/compliance)。

## IDFV

`IDFV` 是 iOS 上的 **Identifier for Vendor**——Apple 为同一开发者在同一设备上的应用分配的 UUID。与 IDFA 不同，IDFV 不需要 ATT 授权，在 iOS 上始终可用。SDK 通过 `UIDevice.current.identifierForVendor` 读取它，并在每次广告请求时作为 IFA 的 iOS 端稳定补充一起发送。

它的作用范围是**同一开发者在同一设备上的所有应用**：同一开发者团队的所有应用在这台设备上共享同一个 IDFV，只有当该开发者的所有应用都被卸载后，IDFV 才会重置。

## 下一步

<CardGroup cols={2}>
  <Card title="会话生命周期" icon="circle-play" href="/concepts/session">
    这些标识符如何在会话中流动，从创建到关闭。
  </Card>

  <Card title="合规" icon="check-double" href="/resources/compliance">
    IFA 和 IDFV 如何与 consent、ATT、AD\_ID、TCF 协作，以及 SDK 会收集哪些数据。
  </Card>
</CardGroup>