跳转到主要内容

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.

​
处理 no-fill

订阅 ad.no-fill 以了解何时没有返回广告（地域限制、频次封顶、服务端跳过等）。payload 中的 skipCode 会说明原因。 
onEvent: ({ name, payload }) => {
  if (name === 'ad.no-fill') {
    console.log('无广告可用:', payload.skipCode)
  }
}
现在每次 preload 都会恰好产生一个 ad.filled / ad.no-fill / ad.error 事件，你可以依赖在每条用户消息后收到回应。

​
传入每一条消息，并用 trackOnly 抑制广告

请始终把每条消息都喂给会话，即使你不希望广告出现（例如用户处于免费试用、所在地区不投放广告、或你只想每 N 条消息展示一次广告）。跳过 addMessage 调用会破坏服务端用于定向的对话上下文。完整模式见 节奏控制。 使用 { trackOnly: true } 让 preload 仅用于分析，不生成广告： 
const shouldShowAd = userMessageCount % 5 === 0

session.addMessage(
  { id: msg.id, role: 'user', content: msg.content, createdAt: new Date() },
  { trackOnly: !shouldShowAd }
)
trackOnly: true 时 preload 仍会发出（服务端保留完整分析数据），但该消息不会触发 ad.filled 事件，对应的 session.createAd(...) 也不会拿到任何广告。 当用户在你的 CMP 中更新了 consent，把新的 TCF 字符串传给 updateOptions： 
session.updateOptions({
  regulatory: { gdpr: 1, gdprConsent: '<new-TCF-string>' },
})
下一次 preload 就会采用新值——无需重建会话。

​
切换 character

进行中的 character 不能实时更新——已累积的消息历史归属于原角色，会话中途切换会让消息被定向到错误的角色。 要切换角色，请销毁当前会话并创建一个新的： 
session.destroy()

session = createSession({
  publisherToken: '<your-publisher-token>',
  userId: 'user-1234',
  conversationId: 'conv-new',
  character: newCharacter,
})
publisherToken、userId、conversationId、enabledPlacementCodes 同理——其中任何一个发生变化时，请重建会话。

​
加载历史消息（会话恢复）

从后端恢复对话时，请按顺序对每条历史消息调用一次 addMessage(...)。Preload 是经过防抖的（约 10 ms），所以连续的快速调用会合并成单次 preload（针对最新的用户消息）——不会出现”每恢复一条消息就发一次 preload”的情况。 
for (const m of loadedFromBackend) {
  session.addMessage({
    id: m.id,
    role: m.role,
    content: m.content,
    createdAt: m.timestamp,
  })
}