React Native SDK

我们正在准备 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` 属性

string

必填

你的 publisher token。

array

必填

用户和助手之间的消息列表。

显示字段

string

必填

消息的唯一 ID。

string

必填

消息角色（user 或 assistant）。

string

必填

消息文本。

Date

必填

消息创建时间戳。

string

必填

在用户整个生命周期内保持不变的唯一标识（用于再营销与奖励广告）。

string

用户邮箱。

string

必填

对话的唯一 ID。

array

必填

本次对话启用的 placement code。例如：['inlineAd']。

object

本次对话使用的 character 对象。

显示字段

string

必填

角色的唯一 ID。

string

必填

角色名称。

string

必填

角色头像 URL。

boolean

标识该角色是否面向成人受众。

string

角色的问候语。

string

角色性格的简要描述。

array

描述角色的标签。

object

合规相关信息。如果你的应用集成了兼容 TCF 的 CMP（Consent Management Platform），SDK 会自动处理 TCF（透明度与同意框架） 信号（gdpr 与 gdprConsent）——你无需手动设置这两个字段。

显示字段

请求是否受 GDPR 约束。（0 = 否，1 = 是，null = 未知）

IAB 透明度与同意框架（TCF）的 consent 字符串。

integer

请求是否受 COPPA 约束。（0 = 否，1 = 是，null = 未知）

string

Global Privacy Platform (GPP) consent 字符串。

array

本次请求适用的 GPP section ID 列表。

string

美国隐私法规（如 CCPA、LSPA）相关的消费者信号。

string

发布方提供的用户分群标识（用于 A/B 测试）。

function

事件发生时的回调。详见下方的支持的事件章节。

boolean

是否禁用广告的标志位。注意：这并不会影响已展示的旧广告；旧广告的处理由 staleAdsHandling 控制。

string

决定如何处理”过期广告”（与最新消息不再关联的广告）。

preserve —— 继续展示最近锚定的广告，直到有新广告替换它
hide（默认）—— 一旦广告过期就隐藏

`InlineAd` 属性

string

必填

Onboarding 时提供的 placement code。

string

必填

消息的唯一 ID。

string

广告主题，例如 light 或 dark。

function

用于包装广告内容的函数。

支持的事件

`ad.clicked`

用户点击了广告。

显示 Payload

string

广告 ID。

string

生成的广告内容。

string

消息 ID。

string

点击跳转的 URL。

string

广告形式。

`ad.viewed`

用户已查看广告。

显示 Payload

string

广告 ID。

string

生成的广告内容。

string

消息 ID。

string

广告形式。

number

广告收入（美元计的 eCPM）。

`ad.filled`

有可投放的广告。

显示 Payload

number

广告收入（美元计的 eCPM）。

`ad.no-fill`

没有可投放的广告。

显示 Payload

string

指示广告被跳过原因的代码。

`ad.render-started`

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

显示 Payload

string

广告 ID。

`ad.render-completed`

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

显示 Payload

string

广告 ID。

`ad.error`

出现错误时触发。

显示 Payload

string

错误信息。

string

错误代码。

`reward.granted`

用户获得奖励时触发。

显示 Payload

string

广告 ID。

`video.started`

视频开始播放时触发。

显示 Payload

string

广告 ID。

`video.completed`

视频播放完成时触发。

显示 Payload

string

广告 ID。

实践指南

处理 no-fill 事件

可以通过 onEvent 回调感知广告何时不可用。

<AdsProvider
  // ...
  onEvent={({ name, payload }) => {
    if (name === 'ad.no-fill') {
      console.log('Ad is not available');
    }
  }}
/>

入门

核心概念

实践指南

SDK

资源

React Native Demo 项目

环境要求

快速开始

1. 安装

2. 初始化 AdsProvider

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

4. 配置 SKAdNetwork（仅 iOS）

5. 展示你的第一个广告

API 文档

`AdsProvider` 属性

`InlineAd` 属性

支持的事件

`ad.clicked`

`ad.viewed`

`ad.filled`

`ad.no-fill`

`ad.render-started`

`ad.render-completed`

`ad.error`

`reward.granted`

`video.started`

`video.completed`

实践指南

处理 no-fill 事件

链接

React Native Demo 项目

​环境要求

​快速开始

​1. 安装

​2. 初始化 AdsProvider

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

​4. 配置 SKAdNetwork（仅 iOS）

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

​API 文档

​AdsProvider 属性

​InlineAd 属性

​支持的事件

​ad.clicked

​ad.viewed

​ad.filled

​ad.no-fill

​ad.render-started

​ad.render-completed

​ad.error

​reward.granted

​video.started

​video.completed

​实践指南

​处理 no-fill 事件

​链接

环境要求

快速开始

1. 安装

2. 初始化 AdsProvider

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

4. 配置 SKAdNetwork（仅 iOS）

5. 展示你的第一个广告

API 文档

`AdsProvider` 属性

`InlineAd` 属性

支持的事件

`ad.clicked`

`ad.viewed`

`ad.filled`

`ad.no-fill`

`ad.render-started`

`ad.render-completed`

`ad.error`

`reward.granted`

`video.started`

`video.completed`

实践指南

处理 no-fill 事件

链接