ID 与 token

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.

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

​

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 一一绑定——具体的复用与重建规则见 会话生命周期。 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 会回退到一个内部生成的第一方标识符。同意与平台政策细节见 合规。

​

IDFV

IDFV 是 iOS 上的 Identifier for Vendor——Apple 为同一开发者在同一设备上的应用分配的 UUID。与 IDFA 不同，IDFV 不需要 ATT 授权，在 iOS 上始终可用。SDK 通过 UIDevice.current.identifierForVendor 读取它，并在每次广告请求时作为 IFA 的 iOS 端稳定补充一起发送。 它的作用范围是同一开发者在同一设备上的所有应用：同一开发者团队的所有应用在这台设备上共享同一个 IDFV，只有当该开发者的所有应用都被卸载后，IDFV 才会重置。

​

下一步