互动式媒体广告 (IMA) 动态广告插播 (DAI) SDK 依赖嵌入在视频流的媒体片段(带内元数据)或流式清单文件(清单内元数据)中的元数据信息来跟踪观看者的位置和客户端广告事件。元数据以不同的格式发送,具体取决于播放的数据流类型。
视频播放器批量接收定时元数据。元数据可在预定时间显示,也可批量显示,具体取决于播放器。每个元数据字符串都有一个关联的呈现时间戳 (PTS),用于指明应在何时触发该时间戳。
您的应用负责捕获元数据并将其转发到 IMA DAI SDK。SDK 提供了以下方法来传递此信息:
- onTimedMetadata
此方法会将已准备好处理的元数据字符串转发到 SDK。它接受一个参数:
metadata
:一个对象,其中包含一个TXXX
键以及关联的字符串值,该键以google_
为前缀。
- processMetadata
此方法安排在指定 PTS 之后由 SDK 处理元数据字符串。它采用以下参数:
type
:一个字符串,其中包含要处理的事件的类型。接受的值为ID3
(对于 HLS)或urn:google:dai:2018
(对于 DASH)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。无需将示例数据从字节数组解码为字符串,也无需滤除不相关的 ID3 代码,因为 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);
});
}
});
...
HLS CMAF 视频流
使用通用媒体应用框架 (CMAF) 的线性 DAI HLS 视频流按照从 ID3 到 CMAF 的标准通过带内 eMSGv1 框传递定时元数据。这些 eMSG 框嵌入每个媒体段的开头,其中每个 ID3 eMSG 都包含相对于流中最后一个不连续性的 PTS。
从 HLS.js 1.2.0 版本开始,我们建议的两种播放器通过 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 将 ID3 到 eMSG 的元数据视为伪 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 播放器
Shaka 播放器会将活动作为其 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 Player(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 视频流的 Shaka 播放器(DASH 视频流格式)
如果您使用 Shaka 播放器进行 VOD 流播放,请使用字符串 '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);
}
}