跳转到主要内容

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.

广告组件（<InlineAd messageId="..." /> 或各平台的等价组件）本质上是一次查找：它会把 SDK 缓存中、以你传入的 messageId 索引的那条广告渲染出来。 SDK 会自动把每条返回的广告与最新一条助手消息配对。当你调用 addMessage('assistant', { id: 'msg-42', ... }) 时，下一条可用的广告就会以这个 id 缓存。所以 <InlineAd> 的规则非常简单：传入广告应该紧跟其后的那条助手消息的 id。时序由 SDK 自动处理——无论预加载是在助手消息之前还是之后返回，只要两者都就绪，广告就会出现。

​
流程

1

用户发送消息

你的应用调用 session.addMessage({ role: 'user', ... })。在助手还在生成回复的同时，SDK 会在后台触发一次防抖后的 POST /preload。
2

助手回复——并带有自己的稳定 id（例如 "msg-42"）

你的应用收到助手消息后调用 session.addMessage({ id: 'msg-42', role: 'assistant', ... })。SDK 把预加载到的广告绑定到这个 id。
3

按助手消息的 id 挂载广告组件

在 UI 中紧跟该助手回复的位置渲染 <InlineAd messageId="msg-42" />。SDK 会根据 messageId="msg-42" 查找已绑定的广告，并在 iframe 中渲染——其内容会延续助手的语气。
虽然预加载是在用户消息添加时触发的，但广告最终绑定的是助手消息的 id，而不是用户消息的 id。正因如此，广告才会出现在为它提供上下文的那一轮助手回复正下方。

​
“最新助手消息”模式

绝大多数聊天 UI 中，广告位就放在最新一条助手消息下面。把 <InlineAd> 绑定到该消息的 id，就覆盖了这一通用场景。 
{messages.map((m) => (
  <div key={m.id}>
    <Message message={m} />
    {m.role === 'assistant' && m.id === latestAssistantId && (
      <InlineAd messageId={m.id} />
    )}
  </div>
))}

​
常见错误

  • 绑定到了用户消息的 id。 用户消息只是预加载的触发点，但广告是绑定到其后到达的助手消息 id 的。请把 <InlineAd> 绑定到助手消息的 id。
  • 每次按键都重建组件。 请使用稳定的 Vue/React key={messageId}，避免在内容流式输出过程中组件被卸载又重建。

​
下一步

消息

addMessage 接收的字段，以及稳定 ID 的重要性。

广告形式

Inline、interstitial、reward——每种形式做什么、适配哪种广告位。

广告生命周期事件

广告真正渲染后 SDK 会发出哪些事件。