使用JS方法实现客户端广告插入
使用JS方法实现客户端广告插入
开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅最新的发布说明。
在本教程中，您将使用JS方法在Vega应用中实现客户端广告插入 (CSAI)。这种方法使用直接React Native组件集成，其中VideoPlayer实例在用户界面组件层中创建和管理。您将设置一个双播放器架构，其中一个主播放器用于播放内容，一个广告播放器在广告插播期间接管共享视频展示位。
本教程中的示例演示了用于实现无缝广告过渡的预缓冲广告。有关CSAI概念、技巧和同步策略的背景信息，请参阅Vega中的客户端广告插入。
在本教程中，您将学习如何：
- 设置播放器引用和导入
- 检测广告标记并预初始化广告播放器
- 等待广告缓冲，然后暂停主要内容
- 切换视频展示位并播放广告
- 广告结束后返回至主要内容
先决条件
- Vega开发环境已设置
- Vega SDK v0.22或更高版本
@amazon-devices/react-native-w3cmedia程序包已安装- 主内容播放器已经初始化并正在播放
- React Native和TypeScript的基础知识
设置播放器引用
导入所需的组件，为主播放器、广告播放器和共享的展示位句柄创建引用。
import { VideoPlayer, KeplerVideoSurfaceView } from '@amazon-devices/react-native-w3cmedia';
// 播放器引用
const videoPlayer = useRef<VideoPlayer | null>(null); // 主内容播放器（已初始化）
const adVideoPlayer = useRef<VideoPlayer | null>(null); // 广告播放器
const cachedSurface = useRef<any>(null); // 共享展示位句柄
检测广告标记并预初始化广告播放器
当应用检测到即将到来的广告插播时（例如，广告开始前5秒），预先初始化广告播放器，并使用autoPlay=false开始缓冲广告内容。
- 在主播放器上注册
timeupdate侦听器，以检测即将到来的广告插播。
videoPlayer.current.addEventListener('timeupdate', () => {
const currentTime = videoPlayer.current?.currentTime || 0;
// 用于确定广告插播是否临近的应用特定逻辑
//（例如，VMAP计划、边车文件、硬编码列表或广告SDK回调）
if (adBreakApproaching(currentTime)) {
initializeAdPlayer(AD_CONTENT_URL);
}
});
- 创建广告播放器初始化函数。将
autoPlay设置为false，这样您就可以控制何时开始播放。
const initializeAdPlayer = async (adUrl: string) => {
adVideoPlayer.current = new VideoPlayer();
await adVideoPlayer.current.initialize();
adVideoPlayer.current.autoplay = false;
adVideoPlayer.current.addEventListener('canplay', onAdReady);
adVideoPlayer.current.addEventListener('ended', onAdEnded);
adVideoPlayer.current.src = adUrl;
};
等待广告缓冲，然后暂停主要内容
在广告播放器发出已完成缓冲信号 (canplay) 且达到广告开始时间后，暂停主要内容。
const onAdReady = () => {
// 广告已缓冲 — 等待预定的广告开始时间
// 当位置侦听器检测到广告开始时间已到时：
videoPlayer.current?.pause();
};
切换展示位并播放广告
当主要内容暂停时，清理主播放器的展示位并将其分配给广告播放器。
videoPlayer.current.addEventListener('pause', () => {
// 清理主播放器展示位并分配给广告播放器
videoPlayer.current?.clearSurfaceHandle(cachedSurface.current);
adVideoPlayer.current?.setSurfaceHandle(cachedSurface.current);
adVideoPlayer.current?.play();
});
返回至主要内容
广告结束后，清理广告展示位，清理广告播放器，然后恢复主要内容。
const onAdEnded = async () => {
adVideoPlayer.current?.clearSurfaceHandle(cachedSurface.current);
videoPlayer.current?.setSurfaceHandle(cachedSurface.current);
videoPlayer.current?.play();
await adVideoPlayer.current?.deinitialize();
adVideoPlayer.current = null;
};
清理资源
当您的组件卸载或播放器会话结束时，取消两个播放器的初始化并释放展示位句柄。
const cleanup = async () => {
if (adVideoPlayer.current) {
await adVideoPlayer.current.deinitialize();
adVideoPlayer.current = null;
}
// 主播放器清理工作通过您现有的拆解逻辑处理
};
相关内容
Last updated: 2026年3月13日
