Interactive Media Ads(IMA)ダイナミック広告挿入(DAI)SDK は、ストリームのメディア セグメント(インバンド メタデータ)またはストリーミング マニフェスト ファイル(マニフェスト内メタデータ)に埋め込まれたメタデータ情報を利用して、視聴者の位置情報とクライアントサイドの広告イベントを追跡します。メタデータは 再生中のストリームの種類に応じて 異なる形式で送信されます
動画プレーヤーは、時間指定メタデータを一括で受け取ります。プレーヤーに応じて、メタデータはスケジュールされた時刻に、または一括して表示できます。各メタデータ文字列には、トリガーされるタイミングを示すプレゼンテーション タイムスタンプ(PTS)が関連付けられています。
アプリはメタデータを取得して IMA DAI SDK に転送する役割を担います。SDK には、この情報を渡すための次のメソッドが用意されています。
- onTimedMetadata
このメソッドは、処理の準備ができているメタデータ文字列を SDK に転送します。引数は 1 つです。
metadata
:google_
で始まる関連付けられた文字列値を持つTXXX
のキーを含むオブジェクト。
- processMetadata
このメソッドは、指定された PTS の後に SDK がメタデータ文字列を処理するようにスケジュールします。次の引数を取ります。
type
: 処理されるイベントのタイプを含む文字列。指定できる値は、HLS の場合はID3
、DASH の場合はurn:google:dai:2018
です。data
:google_
の接頭辞が付いた文字列値か、そのような文字列にデコードされるバイト配列。timestamp
: データを処理するときのタイムスタンプ(秒単位)。
IMA DAI SDK でサポートされている各ストリーム タイプでは、以降のセクションで説明するように、固有の形式の時間メタデータを使用します。
HLS MPEG2TS ストリーム
MPEG2TS セグメントを使用するリニア DAI HLS ストリームは、インバンド ID3 タグを介して時間指定メタデータを動画プレーヤーに渡します。これらの ID3 タグは MPEG2TS セグメントに埋め込まれ、TXXX フィールド名(ユーザー定義のテキスト コンテンツ用)が付けられます。
Safari での再生
Safari は ID3 タグを隠しトラックとして自動的に処理するため、cuechange イベントが適切なタイミングで呼び出され、各メタデータが処理されます。コンテンツやタイプに関係なく、すべてのメタデータを IMA DAI SDK に渡しても問題ありません。無関係なメタデータは自動的に除外されます。
次の例をご覧ください。
videoElement.textTracks.addEventListener('addtrack', (e) => {
const track = e.track;
if (track.kind === 'metadata') {
track.mode = 'hidden';
track.addEventListener('cuechange', () => {
for (const cue of track.activeCues) {
const metadata = {};
metadata[cue.value.key] = cue.value.data;
streamManager.onTimedMetadata(metadata);
}
});
}
});
...
HLS.js
HLS.js では、FRAG_PARSING_METADATA
イベントを通じて、ID3 タグをサンプルの配列として一括で提供します。HLS.js は、ID3 データをバイト配列から文字列に変換せず、対応する PTS にイベントをオフセットしません。IMA DAI SDK では、このデコードとフィルタリングが自動的に行われるため、サンプルデータをバイト配列から文字列にデコードしたり、無関係な ID3 タグを除外したりする必要はありません。
次の例をご覧ください。
hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
if (streamManager && data) {
data.samples.forEach((sample) => {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
});
...
HLS CMAF ストリーム
Common Media Application Framework(CMAF)を使用するリニア DAI HLS ストリームは、ID3 ~ CMAF 標準に従い、インバンド eMSGv1 ボックスを通じて時間指定メタデータを渡します。これらの eMSG ボックスは、各メディア セグメントの先頭に埋め込まれ、各 ID3 eMSG には、ストリームの最後の不連続性に対する PTS が含まれます。
HLS.js 1.2.0 リリースの時点では、Google が推奨するプレーヤーはどちらも、CMAF を通じて ID3 を ID3 タグであるかのようにユーザーに渡します。このため、次の例は HLS MPEG2TS ストリームの場合と同じです。ただし、これはすべてのプレーヤーに当てはまるわけではないため、HLS CMAF ストリームのサポートを実装するには、eMSG を通じて ID3 を解析するために一意のコードが必要になる場合があります。
Safari での再生
Safari は、ID3 から eMSG メタデータを疑似 ID3 イベントとして扱い、自動的に隠しトラックとして一括して提供します。これにより、各メタデータを処理する適切なタイミングで cuechange イベントが発行されます。タイミングに関連するかどうかにかかわらず、すべてのメタデータを IMA DAI SDK に渡しても問題ありません。DAI 関連以外のメタデータは自動的に除外されます。
次の例をご覧ください。
videoElement.textTracks.addEventListener('addtrack', (e) => {
const track = e.track;
if (track.kind === 'metadata') {
track.mode = 'hidden';
track.addEventListener('cuechange', () => {
for (const cue of track.activeCues) {
const metadata = {};
metadata[cue.value.key] = cue.value.data;
streamManager.onTimedMetadata(metadata);
}
});
}
});
...
HLS.js
バージョン 1.2.0 より、HLS.js は eMSG メタデータを通じて ID3 を疑似 ID3 イベントとして扱い、FRAG_PARSING_METADATA
イベントを通じてバッチでサンプルの配列として提供します。HLS.js は、ID3 データをバイト配列から文字列に変換せず、イベントを対応する PTS にオフセットしません。IMA DAI SDK ではこのデコードが自動的に実行されるため、サンプルデータをバイト配列から文字列にデコードする必要はありません。
次の例をご覧ください。
hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
if (streamManager && data) {
data.samples.forEach((sample) => {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
});
...
DASH ストリーム
リニア DAI DASH ストリームは、カスタム schemeIdUri
値 urn:google:dai:2018
を使用して、イベント ストリームのマニフェスト イベントとしてメタデータを渡します。これらのストリームの各イベントには、テキスト ペイロードと PTS が含まれます。
DASH.js
Dash.js には、各イベント ストリームの schemeIdUri 値に基づいて名前が付けられたカスタム イベント ハンドラが用意されています。これらのカスタム ハンドラは一括で起動され、PTS 値を処理してイベントの適切な時間を設定するかどうかはユーザー次第です。IMA DAI SDK では、streamManager メソッドの processMetadata()
を使用してこの処理を行うことができます。
次の例をご覧ください。
const dash = dashjs.MediaPlayer().create();
dash.on('urn:google:dai:2018', (payload) => {
const mediaId = payload.event.messageData;
const pts = payload.event.calculatedPresentationTime;
streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
});
...
Shaka Player
Shaka Player は timelineregionenter
イベントの一部としてイベントを表示します。Shaka Player とフォーマットには互換性がないため、メタデータ値は詳細プロパティ eventElement.attributes['messageData'].value
を使用して未加工で取得する必要があります。
次の例をご覧ください。
player.addEventListener('timelineregionenter', function(event) {
const detail = event.detail;
if ( detail.eventElement.attributes &&
detail.eventElement.attributes['messageData'] &&
detail.eventElement.attributes['messageData'].value) {
const mediaId = detail.eventElement.attributes['messageData'].value;
const pts = detail.startTime;
streamManager.processMetadata("urn:google:dai:2018", mediaId, pts);
}
});
...
連続配信広告
Pod サービングの場合、時間指定メタデータを渡すための構成は、次の基準に応じて異なります。
- ライブまたは VOD のストリームの種類
- HLS または DASH ストリーム形式
- 使用するプレーヤーのタイプ
- 使用する DAI バックエンドのタイプ
HLS ストリーム形式(ライブ ストリームと VOD ストリーム、HLS.js プレーヤー)
HLS.js プレーヤーを使用している場合は、HLS.js の FRAG_PARSING_METADATA
イベントをリッスンして ID3 メタデータを取得し、StreamManager.processMetadata()
を使用して SDK に渡します。
すべてが読み込まれて準備が整った後で動画を自動的に再生するには、HLS.js の MANIFEST_PARSED
イベントをリッスンして再生をトリガーします。
function loadStream(streamID) {
hls.loadSource(url);
hls.attachMedia(videoElement);
// Timed metadata is passed HLS stream events to the streamManager.
hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}
function parseID3Events(event, data) {
if (streamManager && data) {
// For each ID3 tag in the metadata, pass in the type - ID3, the
// tag data (a byte array), and the presentation timestamp (PTS).
data.samples.forEach((sample) => {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
}
function startPlayback() {
console.log('Video Play');
videoElement.play();
}
DASH.js(DASH ストリーム形式、ライブ、VOD ストリーム タイプ)
DASH.js プレーヤーを使用している場合、ライブ ストリームまたは VOD ストリームの ID3 メタデータをリッスンするには、次のように異なる文字列を使用する必要があります。
- ライブ配信:
'https://developer.apple.com/streaming/emsg-id3'
- VOD ストリーム:
'urn:google:dai:2018'
StreamManager.processMetadata()
を使用して、ID3 メタデータを SDK に渡します。
すべてが読み込まれて準備ができたら、動画コントロールを自動的に表示するには、DASH.js の MANIFEST_LOADED
イベントをリッスンします。
const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
function processMetadata(metadataEvent) {
const messageData = metadataEvent.event.messageData;
const timestamp = metadataEvent.event.calculatedPresentationTime;
// Use StreamManager.processMetadata() if your video player provides raw
// ID3 tags, as with dash.js.
streamManager.processMetadata('ID3', messageData, timestamp);
}
function loadlistener() {
showControls();
// This listener must be removed, otherwise it triggers as addional
// manifests are loaded. The manifest is loaded once for the content,
// but additional manifests are loaded for upcoming ad breaks.
dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}
ライブ配信を行う Shaka プレーヤー(DASH ストリーム形式)
ライブ配信の再生に Shaka プレーヤーを使用している場合は、文字列 'emsg'
を使用してメタデータ イベントをリッスンします。次に、StreamManager.onTimedMetadata()
の呼び出しで、そのイベント メッセージ データを使用します。
shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));
function onEmsgEvent(metadataEvent) {
// Use StreamManager.onTimedMetadata() if your video player provides
// processed metadata, as with Shaka player livestreams.
streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}
VOD ストリーム(DASH ストリーム形式)を使用する Shaka プレーヤー
VOD ストリームの再生に Shaka プレーヤーを使用している場合は、文字列 'timelineregionenter'
を使用してメタデータ イベントをリッスンします。次に、StreamManager.processMetadata()
の呼び出しで、このイベント メッセージ データを文字列 'urn:google:dai:2018'
とともに使用します。
shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));
function onTimelineEvent(metadataEvent) {
const detail = metadataEvent.detail;
if ( detail.eventElement.attributes &&
detail.eventElement.attributes['messageData'] &&
detail.eventElement.attributes['messageData'].value ) {
const mediaId = detail.eventElement.attributes['messageData'].value;
const pts = detail.startTime;
// Use StreamManager.processMetadata() if your video player provides raw
// ID3 tags, as with Shaka player VOD streams.
streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
}
}