跳转到主要内容

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 会说明原因。 
app.use(KontextAdsPlugin, {
  // ...
  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 { addMessage } = useAds()
const shouldShowAd = userMessageCount.value % 5 === 0

addMessage(
  { id: msg.id, role: 'user', content: msg.content, createdAt: new Date() },
  { trackOnly: !shouldShowAd }
)
trackOnly: true 时 preload 仍会发出（服务端保留完整分析数据），但该消息不会触发 ad.filled 事件，对应的 <InlineAd> 也不会渲染内容。 插件（或 <AdsProvider>）会把新的 props 响应式地传给底层会话。把 regulatory 绑定到你 CMP 的状态，下一次 preload 会自动采用新值： 
<AdsProvider
  :publisher-token="publisherToken"
  :user-id="userId"
  :conversation-id="conversationId"
  :regulatory="{ gdpr: gdprConsent.applies ? 1 : 0, gdprConsent: gdprConsent.tcString }"
>
  <Chat />
</AdsProvider>
无需重建会话。

​
切换 character

进行中的 character 不能实时更新——已累积的消息历史归属于原角色，会话中途切换会让消息被定向到错误的角色。 要切换角色，请同时修改 <AdsProvider> 上的 conversationId（与 character）prop。Provider 会自动销毁原会话并创建新会话： 
<AdsProvider
  :publisher-token="publisherToken"
  :user-id="userId"
  :conversation-id="conversationId"
  :character="currentCharacter"
>
  <Chat />
</AdsProvider>
publisherToken、userId、conversationId、enabledPlacementCodes 同理——其中任何一个变化都会重建会话。

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

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

for (const m of loadedFromBackend) {
  addMessage({
    id: m.id,
    role: m.role,
    content: m.content,
    createdAt: m.timestamp,
  })
}