JSアプローチを使用したクライアント側広告挿入の実装
このチュートリアルでは、JSアプローチを使用してVegaアプリにクライアント側広告挿入（CSAI）を実装します。このアプローチでは、React Nativeコンポーネントを直接統合し、UIコンポーネントレイヤー内で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日
