Session（会话） 表示一次聊天对话。它是 SDK 的核心组织单元——承载对话上下文、广告缓存、活跃的网络请求以及事件流。每一次 Kontext 接入都遵循相同的会话生命周期，即使各 SDK 的 API 形态略有不同。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.
一次对话对应一个会话
会话绑定到一个用户的一次对话。当用户开始新对话时，使用新的conversationId 创建一个新会话。不要在多个对话之间复用同一个会话。
| 场景 | 应该怎么做 |
|---|---|
| 用户在同一对话中又发了一条消息 | 复用现有会话——直接调用 addMessage。 |
| 用户开始新对话 | 关闭当前会话，并用新的 conversationId 创建一个新会话。 |
| 用户退出登录 / 另一个用户登录 | 关闭当前会话，并用新的 userId 创建一个新会话。 |
| 应用被后台并恢复，对话仍是同一个 | 如果会话仍在则继续复用；如果不在，则创建新会话，SDK 会基于现有消息重新填充缓存。 |
四个阶段
无论用哪个 SDK，每个会话都会走过相同的四个阶段。1. 创建
创建会话时需要传入描述这次对话的 ID 与选项：publisherToken—— onboarding 时发放，用于标识你的账号。userId—— 该用户的稳定标识，跨对话保持不变。conversationId—— 当前对话的唯一标识。- 可选项：
character、regulatory、variantId，以及事件和调试回调。
POST /init。响应中携带服务端控制的开关：会话是否 enabled、preloadTimeout，以及两个遥测开关（reportErrors、reportDebug）。这些值在会话生命周期内保持不变——若需要刷新，请重建会话。
2. 喂消息
对话进行时，应用为每条新消息调用一次addMessage。用户消息和助手消息都需要传入——SDK 使用完整的对话上下文（而不仅是最后一条消息）来寻找上下文相关的广告。
每次 addMessage 都会触发一次防抖后的 POST /preload。SDK 会把返回的广告与助手消息 id 配对，并为每条 message 触发 filled 或 no-fill 事件。
每条消息需要包含哪些字段、为什么 ID 要稳定，详见 消息。
3. 监听事件
会话也是 SDK 向你的应用反馈的通道。事件统一从同一个流中发出：- 预加载期事件 —— 在
/preload返回时按messageId触发filled或no-fill。 - 渲染期事件 —— 当挂载的广告组件在展示广告时，触发
viewed、clicked、error，以及（适用时）视频和奖励事件。
Flow、React 事件 prop 等等。完整事件列表与含义见 广告生命周期事件。
4. 关闭
对话结束时，请关闭会话。关闭会：- 取消所有进行中的
/preload、/error、/debug请求。 - 释放广告缓存。
- 停止事件流。
close() 关闭。声明式 SDK（React、React Native、Vue、Flutter）会在 AdsProvider 卸载时自动关闭会话，无需你额外调用。
忘记关闭命令式会话会泄漏资源，但并不致命——为同一用户下一次创建会话仍能正常工作。
可变 vs 不可变选项
创建时传入的大多数选项是不可变的——若要修改，请关闭当前会话并重建一个。少数选项在运行时可变；常见的包括 regulatory 对象（CMP 弹窗后 consent 字符串会变化），以及部分 SDK 的 character。可变面被刻意控制得很小，以保持广告缓存与对话上下文的一致性。 你所用平台上哪些选项可变、以及如何更新，请参考对应的 SDK 页面。下一步
ID 与 token
会话上每个 ID 的含义与生成方。
消息
addMessage 接收什么字段，以及稳定 ID 的重要性。广告生命周期事件
会话发出的所有事件及其含义。