跳转到主要内容

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.

我们正在准备 React Native SDK 的 v4 版本。下方文档对应当前正式版本——一旦 v4 发布，本页会同步更新。

React Native Demo 项目

看看用我们轻量的 SDK 接入高性能广告有多简单。

​
环境要求

  • React Native：0.73.2 或更高版本

​
快速开始

​
1. 安装

在开始之前，你需要先建立一个 发布方账号 来获取 publisherToken 和 code。
# 安装 SDK
npm install @kontextso/sdk-react-native

# 安装必需的 peer dependencies
npm install react-native-device-info react-native-webview @react-native-community/netinfo

​
2. 初始化 AdsProvider

AdsProvider 负责所有数据获取逻辑，必须能访问到聊天消息。请把它放在组件树的足够上层，以包含所有的广告位。 
import * as React from 'react'
import { useState } from 'react'
import { View } from 'react-native'
import { AdsProvider } from '@kontextso/sdk-react-native'

interface Message {
  id: string
  role: 'user' | 'assistant'
  content: string
  createdAt: Date
}

function App() {
  const [messages, setMessages] = useState<Message[]>([])

  return (
    <AdsProvider
      publisherToken="<publisher-token>"
      messages={messages}
      userId='user-1234'
      conversationId='conv-5678'
      enabledPlacementCodes={['inlineAd']}
      character={{
        id: 'character-1234',
        name: 'John Doe',
        avatarUrl: 'https://example.com/avatar.png',
        greeting: 'Hello, how can I help you today?'
      }}
      regulatory={{
        coppa: 0,
        // ... 其他合规属性
      }}
      onEvent={({ name, code, payload }) => {
        // 处理事件
      }}
    >
      <TheRestOfYourApplication />
    </AdsProvider>
  )
}

​
3. 配置 IFA（广告标识符）

  • iOS： 在 ios/<YourApp>/Info.plist 中加入 NSUserTrackingUsageDescription。SDK 会自动触发 ATT 弹窗并据此读取 IDFA。
  • Android： SDK 通过 manifest merger 自动加入 com.google.android.gms.permission.AD_ID——你无需修改 AndroidManifest.xml。
完整设置见 IFA 与 ATT——必填 key、弹窗时机的坑，以及如何自己管理弹窗。

​
4. 配置 SKAdNetwork（仅 iOS）

请把 onboarding 时提供的 SKAdNetwork 标识符追加到 ios/<YourApp>/Info.plist 中。SDK 会读取它们，并在每次 /init 时一并转发，以便 DSP 衡量转化。 完整指南见 SKAdNetwork。

​
5. 展示你的第一个广告

广告位（ad slot）是 UI 中专门用来渲染广告的区域，通常出现在聊天消息下方。Onboarding 时，你会拿到每个广告位的唯一 code。 把 <InlineAd /> 放在希望广告出现的位置，并为 messageId 传入唯一标识。例如，在 MessageList 组件中，可以在每条消息后渲染一个广告（由于每条消息的 messageId 不同，展示的广告也会各自独立）。 
function MessageList({ messages }: { messages: Message[] }) {
  return (
    <View>
      {messages.map((m) => (
        <View key={m.id}>
          <Message message={m} />
          <InlineAd code="<your-code>" messageId={m.id} />
        </View>
      ))}
    </View>
  )
}

​
API 文档

​
AdsProvider 属性

​
publisherToken
string
必填
你的 publisher token。
​
messages
array
必填
用户和助手之间的消息列表。
​
userId
string
必填
在用户整个生命周期内保持不变的唯一标识（用于再营销与奖励广告）。
​
userEmail
string
用户邮箱。
​
conversationId
string
必填
对话的唯一 ID。
​
enabledPlacementCodes
array
必填
本次对话启用的 placement code。例如：['inlineAd']。
​
character
object
本次对话使用的 character 对象。
​
regulatory
object
合规相关信息。如果你的应用集成了兼容 TCF 的 CMP（Consent Management Platform），SDK 会自动处理 TCF（透明度与同意框架） 信号（gdpr 与 gdprConsent）——你无需手动设置这两个字段。
​
variantId
string
发布方提供的用户分群标识（用于 A/B 测试）。
​
onEvent
function
事件发生时的回调。详见下方的支持的事件章节。
​
isDisabled
boolean
是否禁用广告的标志位。注意：这并不会影响已展示的旧广告；旧广告的处理由 staleAdsHandling 控制。
​
staleAdsHandling
string
决定如何处理”过期广告”（与最新消息不再关联的广告）。
  • preserve —— 继续展示最近锚定的广告，直到有新广告替换它
  • hide（默认）—— 一旦广告过期就隐藏

​
InlineAd 属性

​
code
string
必填
Onboarding 时提供的 placement code。
​
messageId
string
必填
消息的唯一 ID。
​
theme
string
广告主题，例如 light 或 dark。
​
wrapper
function
用于包装广告内容的函数。

​
支持的事件

​
ad.clicked

用户点击了广告。

​
ad.viewed

用户已查看广告。

​
ad.filled

有可投放的广告。

​
ad.no-fill

没有可投放的广告。

​
ad.render-started

在第一个 token 到达之前触发。

​
ad.render-completed

在最后一个 token 到达之后触发。

​
ad.error

出现错误时触发。

​
reward.granted

用户获得奖励时触发。

​
video.started

视频开始播放时触发。

​
video.completed

视频播放完成时触发。

​
实践指南

​
处理 no-fill 事件

可以通过 onEvent 回调感知广告何时不可用。 
<AdsProvider
  // ...
  onEvent={({ name, payload }) => {
    if (name === 'ad.no-fill') {
      console.log('Ad is not available');
    }
  }}
/>

​
链接