Das Interactive Media Ads (IMA) SDK für die dynamische Anzeigenbereitstellung Metadateninformationen, die in die Mediensegmente des Streams eingebettet sind (In-Band-Metadaten), oder in der Streaming-Manifestdatei (in den Manifest-Metadaten), um die und clientseitige Anzeigenereignisse. Metadaten werden in verschiedenen Formaten gesendet, je nach Art des wiedergegebenen Streams.
Der Videoplayer empfängt zeitgesteuerte Metadaten in Batches. Je nach Player Metadaten können zum geplanten Zeitpunkt oder in Batches angezeigt werden. Alle Metadaten String einen zugehörigen Präsentationszeitstempel (PTS) hat, der angibt, wann er ausgelöst.
Ihre App ist dafür verantwortlich, Metadaten zu erfassen und an das IMA DAI SDK weiterzuleiten. Das SDK bietet die folgenden Methoden zur Weitergabe dieser Informationen:
- onTimedMetadata
Diese Methode leitet Metadaten-Strings, die zur Verarbeitung bereit sind, an den SDK. Hierfür wird nur ein Argument verwendet:
metadata
: ein Objekt, das den SchlüsselTXXX
mit einem verknüpften String enthält Wert mit dem Präfixgoogle_
.
- processMetadata
Bei dieser Methode werden Metadatenstrings geplant, die vom SDK nach der PTS-Wert festgelegt. Hierfür werden folgende Argumente verwendet:
type
: ein String, der den Typ des zu verarbeitenden Ereignisses enthält Akzeptiert Werte sindID3
für HLS oderurn:google:dai:2018
für DASHdata
: Entweder ein Stringwert mit dem Präfixgoogle_
oder ein Byte-Array, das in eine solche Zeichenfolge decodiert.timestamp
: der Zeitstempel in Sekunden, an dem Daten verarbeitet werden sollen.
Für jeden Streamtyp, der vom IMA DAI SDK unterstützt wird, wird eine eigene enthalten, wie in den folgenden Abschnitten beschrieben.
HLS-MPEG2TS-Streams
Lineare HLS-Streams der dynamischen Anzeigenbereitstellung, die die MPEG2TS-Segmente verwenden, übergeben zeitgesteuerte Metadaten an den Videoplayer mit In-Band-ID3-Tags verwenden. Diese ID3-Tags sind in das MPEG2TS-Segmente und erhalten den TXXX-Feldnamen (für benutzerdefinierten Text Inhalt).
Wiedergabe in Safari
Safari verarbeitet ID3-Tags automatisch als verborgene Spur, sodass Cuechange-Ereignisse erfasst werden. zur richtigen Zeit ausgelöst werden, um alle Metadaten zu verarbeiten. Es ist in Ordnung, alle Metadaten in das IMA DAI SDK übertragen, unabhängig von Content oder Typ. Irrelevant Metadaten werden automatisch herausgefiltert.
Beispiel:
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 stellt ID3-Tags in Batches über das FRAG_PARSING_METADATA
-Ereignis bereit,
als Array von Stichproben. HLS.js übersetzt die ID3-Daten nicht aus Byte-Arrays
in Strings eingebunden und Ereignisse nicht mit dem entsprechenden PTS-Wert verrechnet. Es ist nicht
erforderlich, um die Stichprobendaten von einem Byte-Array in einen String zu decodieren oder herauszufiltern
Irrelevante ID3-Tags, da das IMA DAI SDK diese Decodierung und Filterung durchführt
automatisch.
Beispiel:
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-Streams
Lineare HLS-Streams der dynamischen Anzeigenbereitstellung, die die CMAF-Karte (Common Media Application Framework) verwenden zeitgesteuerte Metadaten über In-Band-eMSGv1-Felder nach ID3 bis CMAF-Standard. Diese eMSG-Boxen sind am Anfang jedes Mediensegments eingebettet, wobei jede ID3 eMSG Folgendes enthält: einen PTS-Wert relativ zur letzten Diskontinuität im Stream.
Seit Version 1.2.0 von HLS.js bestehen beide vorgeschlagenen Player die ID3. über CMAF an den Nutzer senden, als ob es sich um ID3-Tags handeln würde. Aus diesem Grund Die folgenden Beispiele sind dieselben wie für HLS MPEG2TS-Streams. Dies könnte jedoch nicht bei allen Akteuren der Fall sein sollte. Die Implementierung der Unterstützung für HLS CMAF Streams können eindeutigen Code erfordern, um ID3 über eMSG zu parsen.
Wiedergabe in Safari
Safari behandelt ID3- bis eMSG-Metadaten als Pseudo-ID3-Ereignisse und stellt sie in automatisch als verborgene Spur, sodass cuechange-Ereignisse zur richtigen Zeit ausgelöst, um alle Metadaten zu verarbeiten. Es ist in Ordnung, alle Metadaten an das IMA DAI SDK übergeben, unabhängig davon, ob dies für den Zeitplan relevant ist oder nicht. Beliebig Metadaten, die sich nicht auf die dynamische Anzeigenbereitstellung beziehen, werden automatisch herausgefiltert.
Beispiel:
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
Ab Version 1.2.0 behandelt HLS.js ID3 über eMSG-Metadaten als Pseudo-ID3.
und stellen sie in Batches über das FRAG_PARSING_METADATA
-Ereignis bereit.
als Array von Stichproben. HLS.js übersetzt die ID3-Daten nicht aus Byte-Arrays
in Strings eingebunden und Ereignisse nicht mit dem entsprechenden PTS-Wert verrechnet. Es ist nicht
erforderlich, um die Beispieldaten von Bytearray in String zu decodieren, da das IMA DAI SDK diese Decodierung automatisch durchführt.
Beispiel:
hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
if (streamManager && data) {
data.samples.forEach((sample) => {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
});
...
DASH-Streams
Bei linearen DASH-Streams für die dynamische Anzeigenbereitstellung werden Metadaten als Manifestereignisse in einem Ereignisstream mit
den benutzerdefinierten schemeIdUri
-Wert urn:google:dai:2018
. Jedes Ereignis in diesen
enthält eine Textnutzlast und den PTS.
DASH.js
Dash.js stellt benutzerdefinierte Ereignis-Handler bereit, die nach dem SchemaIdUri-Wert der einzelnen Elemente benannt sind.
des Ereignisstreams. Diese benutzerdefinierten Handler werden in Batches ausgelöst.
den PTS-Wert verarbeiten muss, damit das Ereignis richtig erfasst wird. Mit dem IMA DAI SDK
mit der streamManager-Methode processMetadata()
.
Beispiel:
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-Spieler
Der Shaka Player zeigt Ereignisse als Teil des timelineregionenter
-Ereignisses an. Fällig
Formatierungsinkompatibilität mit dem Shaka Player aufweist, muss der Metadatenwert
RAW abgerufen, über die Eigenschaft detail
eventElement.attributes['messageData'].value
Beispiel:
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-Bereitstellung
Für die Pod-Auslieferung gibt es verschiedene Konfigurationen für die Übergabe mit zeitlicher Festlegung Metadaten abhängig von den folgenden Kriterien:
- Live- oder VOD-Streamtyp
- HLS- oder DASH-Streamformat
- Der verwendete Player-Typ
- Der Typ des verwendeten Backends für die dynamische Anzeigenbereitstellung
HLS-Streamformat (Live- und VOD-Streams, HLS.js-Player)
Wenn Sie einen HLS.js-Player verwenden, hören Sie
das HLS.js-Ereignis FRAG_PARSING_METADATA
, um ID3-Metadaten abzurufen und an den
SDK mit StreamManager.processMetadata()
.
Wenn das Video automatisch abgespielt werden soll, nachdem alles geladen wurde und fertig ist, hören Sie
HLS.js-Ereignis MANIFEST_PARSED
, um die Wiedergabe auszulösen.
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-Streams-Format, Live- und VOD-Streamtyp)
Wenn du einen DASH.js-Player verwendest, müssen verschiedene Strings verwendet werden, um die ID3-Metadaten für Live- oder VOD-Inhalte zu überwachen. Streams:
- Livestreams:
'https://developer.apple.com/streaming/emsg-id3'
- VOD-Streams:
'urn:google:dai:2018'
Übergib die ID3-Metadaten mit StreamManager.processMetadata()
an das SDK.
Damit die Videosteuerelemente automatisch angezeigt werden, nachdem alles geladen wurde und fertig ist,
auf das DASH.js-Ereignis MANIFEST_LOADED
warten zu können.
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 mit Livestreams (DASH-Stream-Format)
Wenn Sie den Shaka-Player für
für die Livestream-Wiedergabe verwenden, verwenden Sie den String 'emsg'
, um auf Metadatenereignisse zu warten.
Verwenden Sie dann die Daten zu Ereignisnachrichten im Aufruf von 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});
}
Shaka-Player mit VOD-Streams (DASH-Stream-Format)
Wenn Sie den Shaka-Player für
Wiedergabe des VOD-Streams. Verwenden Sie den String 'timelineregionenter'
, um auf
Metadatenereignisse. Verwenden Sie dann die Daten aus Ereignisnachrichten in Ihrem Aufruf, um
StreamManager.processMetadata()
durch den String '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);
}
}