跳转到主要内容

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.

这是 5 分钟接入的完整流程。开始之前，请确认你已经完成 安装。

​
1. 用 <AdsProvider> 包裹你的应用

<AdsProvider> 初始化一个会话，其内部的任意组件都可以通过 useAds() hook 访问到它。请把它放在组件树的足够上层，以包含所有的广告位。 
import { AdsProvider } from '@kontextso/sdk-react'

function App() {
  return (
    <AdsProvider
      publisherToken="<your-publisher-token>"
      userId="user-1234"
      conversationId="conv-5678"
      character={{
        id: 'character-1234',
        name: 'John Doe',
        avatarUrl: 'https://example.com/avatar.png',
        greeting: 'Hello, how can I help you today?',
      }}
      onEvent={({ name, code, payload }) => {
        // 处理事件
      }}
    >
      <TheRestOfYourApplication />
    </AdsProvider>
  )
}

​
2. 向 SDK 喂消息

SDK 会根据新的聊天消息预加载广告。无论是用户消息还是助手消息，每出现一条就用 useAds() 返回的 addMessage() 通知 SDK。 
import { useAds } from '@kontextso/sdk-react'

const { addMessage } = useAds()

// 对话中每条用户消息和助手消息都调用一次。
addMessage({
  id: '<unique-message-id>',
  role: '<user | assistant>',
  content: '<content of the message>',
  createdAt: new Date(),
})

​
3. 挂载 <InlineAd>

广告位（ad slot）是 UI 中专门用来渲染广告的区域，通常出现在助手消息下方。 把 <InlineAd /> 放在希望广告出现的位置，并传入对应助手消息的 messageId。 
import { InlineAd } from '@kontextso/sdk-react'

function MessageList({ messages }: { messages: Message[] }) {
  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <Message message={m} />
          {m.role === 'assistant' && <InlineAd messageId={m.id} />}
        </div>
      ))}
    </div>
  )
}

​
订阅事件

通过 <AdsProvider> 的 onEvent prop 订阅广告生命周期事件。每个事件都有稳定的 name 和类型化的 payload： 
<AdsProvider
  // ...
  onEvent={(event) => {
    switch (event.name) {
      case 'ad.filled':
        console.log('filled:', event.payload.id, 'revenue=', event.payload.revenue)
        break
      case 'ad.clicked':
        console.log('clicked:', event.payload.url)
        break
      case 'ad.no-fill':
        console.log('no fill, skipCode=', event.payload.skipCode)
        break
    }
  }}
>
每个与广告位相关的事件（ad.filled、ad.viewed、ad.clicked、ad.render-*、video.*、reward.granted）的顶层还携带一个 code 字段，标识匹配到的广告位——配置了多个 enabledPlacementCodes 的发布方可以据此区分。会话级事件（ad.no-fill、ad.error）则不带这个字段。 接入期间若需查看 SDK 内部诊断信息，可以再传入 onDebugEvent 回调——它会对 SDK 的每一个内部步骤回调 (name, data?)。