> ## 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.
# API 参考
> createSession、Session、Ad，以及完整事件列表。
## `createSession(options)` → `Session`
为一个具体的**用户**和**对话**创建一个广告会话。
你的 publisher token。
在用户整个生命周期内保持不变的唯一标识（用于个性化、频次封顶、奖励广告）。
对话或聊天线程的唯一 ID。
本次对话启用的 placement code。默认为 `['inlineAd']`。
用于上下文广告匹配与个性化的角色元数据。
角色的唯一 ID。
角色名称。
角色头像 URL。
标识该角色是否面向成人受众。
角色的问候语。
角色性格的简要描述。
描述角色的标签。
隐私 / consent 信号。
请求是否受 GDPR 约束。（0 = 否，1 = 是，null = 未知）
IAB 透明度与同意框架（TCF）的 consent 字符串。
请求是否受 COPPA 约束。（0 = 否，1 = 是，null = 未知）
Global Privacy Platform (GPP) consent 字符串。
本次请求适用的 GPP section ID 列表。
美国隐私法规（如 CCPA、LSPA）相关的消费者信号。
用户邮箱，用于频次封顶的去重。
发布方提供的用户分群标识（用于 A/B 测试）。
每个广告生命周期事件触发时的回调。详见下方"支持的事件"章节。
SDK 内部诊断事件的回调。接收 `(name, data?)`——在接入期间排查 preload / session 行为时很有用。默认关闭。
## `Session` 方法
### `session.addMessage(message, options?)`
向 SDK 注册一条聊天消息。在合适的时机会触发一次防抖后的预加载。
见下方 `Message` 结构。
当为 `true` 时，preload 请求仍会发出（用于分析），但本条消息不会展示广告。
### `session.createAd(messageId, options?)` → `Ad`
为特定助手消息创建一个 `Ad`。该方法不会等待广告——一旦有广告可用就会渲染。对同一个 `messageId` + `code` 多次调用会返回同一个实例。
广告所属助手消息的 ID。
Placement code（默认 `'inlineAd'`）。
传递给广告 iframe 的视觉主题（例如 `'light'`、`'dark'`）。
### `session.render(options)` → `Ad`
`createAd` + `mount` 的一次性便捷封装。
广告所属助手消息的 ID。
作为广告 iframe 宿主的元素。
Placement code（默认 `'inlineAd'`）。
视觉主题。
### `session.updateOptions(partial)`
在活跃会话上实时更新与预加载相关的配置。接受的字段：`variantId`、`regulatory`、`userEmail`、`advertisingId`、`vendorId`。变更会在下次 `/preload` 时读取，因此会在下一条用户消息生效——无需重建会话。
`publisherToken`、`userId`、`conversationId`、`enabledPlacementCodes` 与 `character` **不可**实时更新。会话中途修改它们会让 `/init` 注册与后续请求不一致，或者让已累积的消息历史指向错误的人设。请改为重建会话。
### `session.destroy()`
清理内部状态、取消进行中的预加载，并停止后续预加载请求。请在对话结束或页面卸载时调用。`destroy()` 之后，`addMessage`、`createAd`、`render` 等修改型方法会抛出异常。
### `session.getSessionId()` → `string | null`
服务端分配的 session ID。首次 `/preload` 成功之前为 `null`。
### `session.isDisabled()` → `boolean`
若服务端在 `/init` 响应中永久关闭了该会话（例如地域限制），返回 `true`。后续预加载会被跳过。
### `session.isDestroyed()` → `boolean`
`destroy()` 被调用过则返回 `true`。
### `session.getMessages()` → `readonly Message[]`
会话已记录消息的快照，按插入顺序排列。请勿原地修改，也不要长期缓存——当消息数量超过上限时，内部数组会被替换为裁剪后的副本。
### `session.getPreloadTimeout()` → `number`
当前 `/preload` 请求超时（毫秒）。可能由 `/init` 响应中的服务端配置覆盖。
## `Ad` 方法
### `ad.mount(element)`
把广告 iframe 挂载进指定的 DOM 元素。每个 `Ad` 实例只能挂载一次——重复挂载会抛出异常。
作为广告 iframe 宿主的元素。
### `ad.destroy()`
把 iframe 从 DOM 中移除，并释放所有监听器。幂等——可以安全地多次调用。
## `Message` 结构
消息的唯一、稳定 ID。
消息作者的角色。
消息文本。
消息创建时间戳。
## 支持的事件
### `ad.clicked`
用户点击了广告。
广告 ID。
生成的广告内容。
消息 ID。
点击跳转的 URL。
广告形式。
在素材中的点击区域。
### `ad.viewed`
用户已查看广告。
广告 ID。
生成的广告内容。
消息 ID。
广告形式。
每次曝光的广告收入（美元计的 eCPM）。
### `ad.filled`
有可投放的广告。
广告 ID。
与该广告匹配的 placement code。
每次曝光的广告收入（美元计的 eCPM）。
### `ad.no-fill`
没有可投放的广告。
指示广告被跳过原因的代码。
### `ad.render-started`
在第一个 token 到达之前触发。
广告 ID。
### `ad.render-completed`
在最后一个 token 到达之后触发。
广告 ID。
### `ad.error`
出现错误时触发。
错误信息。
错误代码。
### `video.started`
视频开始播放时触发。
广告 ID。
### `video.completed`
视频播放完成时触发。
广告 ID。
### `reward.granted`
用户在激励广告流程中获得奖励时触发。
广告 ID。