跳转到主要内容
我们正在准备 React SDK 的 v4 版本。下方文档对应当前正式版本——一旦 v4 发布,本页会同步更新。

React Demo 项目

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

环境要求

  • React:18.3.1 或更高版本

快速开始

1. 安装

在开始之前,你需要先建立一个 发布方账号 来获取 publisherToken 和 code。

2. 初始化 AdsProvider

AdsProvider 负责所有数据获取逻辑,必须能访问到聊天消息。请把它放在组件树的足够上层,以包含所有的广告位。

3. 展示你的第一个广告

广告位(ad slot)是 UI 中专门用来渲染广告的区域,通常出现在聊天消息下方。Onboarding 时,你会拿到每个广告位的唯一 code。 把 <InlineAd /> 放在希望广告出现的位置,并为 messageId 传入唯一标识。例如,在 MessageList 组件中,可以在每条消息后渲染一个广告(由于每条消息的 messageId 不同,展示的广告也会各自独立)。

API 文档

AdsProvider 属性

string
必填
你的 publisher token。
array
必填
用户和助手之间的消息列表。
string
必填
在用户整个生命周期内保持不变的唯一标识(用于再营销与奖励广告)。
string
用户邮箱。
string
必填
对话的唯一 ID。
array
必填
本次对话启用的 placement code。例如:['inlineAd']。
object
本次对话使用的 character 对象。
object
本次对话使用的合规(regulatory)对象。
string
发布方提供的用户分群标识(用于 A/B 测试)。
function
事件发生时的回调。详见下方的支持的事件章节。
boolean
是否禁用广告的标志位。注意:这并不会影响已展示的旧广告;旧广告的处理由 staleAdsHandling 控制。
string
决定如何处理”过期广告”(与最新消息不再关联的广告)。
  • preserve —— 继续展示最近锚定的广告,直到有新广告替换它
  • hide(默认)—— 一旦广告过期就隐藏

InlineAd 属性

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

支持的事件

ad.clicked

用户点击了广告。

ad.viewed

用户已查看广告。

ad.filled

有可投放的广告。

ad.no-fill

没有可投放的广告。

ad.render-started

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

ad.render-completed

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

ad.error

出现错误时触发。

video.started

视频开始播放时触发。

video.completed

视频播放完成时触发。

实践指南

控制广告加载时机

你可以通过控制何时把新的 messages 传入 AdsProvider 来微调广告频率,从而动态调整广告与消息的比例。

处理 no-fill 事件

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

链接