Działanie pakietu SDK interaktywnych reklam medialnych (IMA) do dynamicznego wstawiania reklam (DAI) wymaga informacje o metadanych umieszczone w segmentach multimediów strumienia (metadane w paśmie), lub w pliku manifestu strumieniowego przesyłania danych (metadane w pliku manifestu), aby monitorować i zdarzeniami reklamowymi po stronie klienta. Metadane są przesyłane w różnych formatach, w zależności od typu transmisji.
Odtwarzacz otrzymuje zbiorcze metadane z ograniczonym czasem trwania. W zależności od odtwarzacza mogą pojawiać się o zaplanowanym czasie lub partiami. Wszystkie metadane ciąg ma powiązaną sygnaturę czasową prezentacji (PTS), która określa, kiedy powinien .
Twoja aplikacja odpowiada za rejestrowanie metadanych i przekazywanie ich do pakietu IMA DAI SDK. Pakiet SDK umożliwia przekazywanie tych informacji za pomocą tych metod:
- onTimedMetadata
Ta metoda przekazuje ciągi metadanych, które są gotowe do przetworzenia, do SDK. Przyjmuje jeden argument:
metadata: obiekt zawierający kluczTXXXz powiązanym ciągiem znaków. poprzedzonegoogle_.
- processMetadata
Ta metoda planuje przetwarzanie ciągów metadanych przez pakiet SDK po określony punkt PTS. Przyjmuje następujące argumenty:
type: ciąg znaków zawierający typ przetwarzanego zdarzenia. Zaakceptowano wartości toID3w przypadku HLS luburn:google:dai:2018w przypadku DASHdata: ciąg znaków zawierający prefiksgoogle_lub tablica bajtów ma ten formatID3:u\0004u\000u\000u\0000TXXXu\0004u\000u\000u\0000google_xxxxxxxxtimestamp: sygnatura czasowa w sekundach, kiedy dane mają zostać przetworzone.
Każdy typ strumienia obsługiwany przez pakiet IMA DAI SDK używa unikalnej formy metadanych zgodnie z opisem w kolejnych sekcjach.
Strumienie HLS MPEG2TS
Liniowe strumienie DAI HLS korzystające z segmentów MPEG2TS przekazują metadane ograniczone czasowo do za pomocą tagów ID3 w paśmie. Tagi ID3 są umieszczone w sekcji segmentom MPEG2TS z nazwą pola TXXX (w przypadku niestandardowego tekstu zdefiniowanego przez użytkownika) treści).
Odtwarzanie w Safari
Safari automatycznie przetwarza tagi ID3 jako ukrytą ścieżkę, aby zapewnić zdarzenia zmiany sygnału. w odpowiednim momencie do przetworzenia każdego fragmentu metadanych. Można z tobą wszystkie metadane do pakietu IMA DAI SDK niezależnie od treści i typu. Są nie na temat są automatycznie odfiltrowywane.
Oto przykład:
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 udostępnia tagi ID3 partiami za pomocą zdarzenia FRAG_PARSING_METADATA,
w postaci tablicy przykładów. HLS.js nie tłumaczy danych ID3 z tablic bajtów
do ciągów znaków i nie kompensuje zdarzeń do odpowiadającego im PTS. Nie
niezbędne do zdekodowania przykładowych danych z tablicy bajtów do ciągu znaków lub odfiltrowania
nietrafne tagi ID3, ponieważ pakiet IMA DAI SDK dekoduje i filtruje
automatycznie.
Oto przykład:
hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
if (streamManager && data) {
data.samples.forEach((sample) => {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
});
...
Strumienie HLS CMAF
Liniowe strumienie DAI HLS korzystające z karty Common Media Application Framework (CMAF) metadanych z sygnaturą czasową poprzez pola eMSGv1 w paśmie po ciągu ID3 do CMAF. Te pudełka eMSG są umieszczone na początku każdego segmentu multimediów, przy czym każda wiadomość eMSG o identyfikatorze ID3 zawiera PTS względem ostatniej nieciągłości w strumieniu.
Od wersji 1.2.0 pliku HLS.js oba proponowane przez nas odtwarzacze mają już kod ID3 za pomocą CMAF, tak jakby były to tagi ID3. Z tego powodu poniższe przykłady są takie same jak w przypadku strumieni HLS MPEG2TS. Może to jednak spowodować Nie dotyczy to wszystkich graczy, dlatego warto wdrożyć obsługę HLS CMAF. strumienie mogą wymagać unikalnego kodu do analizy ID3 przez eMSG.
Odtwarzanie w Safari
Safari traktuje metadane ID3 przez eMSG jako pseudo zdarzenia ID3, udostępniając je w grupowane automatycznie jako ukrytą ścieżkę, np. zdarzenia cuechange. w odpowiednim momencie do przetworzenia każdego fragmentu metadanych. Można przekazują wszystkie metadane do pakietu IMA DAI SDK, niezależnie od tego, czy są istotne, czy związane z czasem. Dowolne metadane niezwiązane z DAI są automatycznie odfiltrowywane.
Oto przykład:
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
Od wersji 1.2.0 HLS.js traktuje identyfikator ID3 przez metadane eMSG jako pseudo ID3
zdarzeń, przesyłając je partiami za pomocą zdarzenia FRAG_PARSING_METADATA,
w postaci tablicy przykładów. HLS.js nie tłumaczy danych ID3 z tablic bajtów
do ciągów znaków i nie kompensuje zdarzeń do odpowiadającego im PTS. Nie
niezbędne do zdekodowania przykładowych danych z tablicy bajtów do ciągu znaków, ponieważ pakiet IMA DAI SDK wykonuje dekodowanie automatycznie.
Oto przykład:
hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
if (streamManager && data) {
data.samples.forEach((sample) => {
streamManager.processMetadata('ID3', sample.data, sample.pts);
});
}
});
...
Strumienie DASH
Liniowe strumienie DASH z dynamicznym wstawianiem reklam przekazują metadane jako zdarzenia w pliku manifestu w strumieniu zdarzeń,
niestandardową wartość schemeIdUri urn:google:dai:2018. Każde zdarzenie w tych
strumienie zawierają ładunek tekstowy i PTS.
DASH.js
Dash.js udostępnia niestandardowe moduły obsługi zdarzeń o nazwach odpowiadających wartości schemaIdUri każdego z nich
. Moduły obsługi niestandardowych uruchamiają się partiami, od Ciebie zależy
przetwarza wartość PTS, aby odpowiednio ustawić czas zdarzenia. Pakiet IMA DAI SDK obsługuje
to za pomocą metody streamManager: processMetadata().
Oto przykład:
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);
});
...
Gracz Shaka
Shaka Player wyświetla wydarzenia w ramach swojego wydarzenia timelineregionenter. Termin
na niezgodność formatu z Shaka Player, wartość metadanych musi być
pobrano nieprzetworzone dane za pomocą właściwości details
eventElement.attributes['messageData'].value
Oto przykład:
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);
}
});
...
Blok reklamowy
W przypadku obsługi podów istnieją różne konfiguracje przekazywania w czasie metadanych w zależności od tych kryteriów:
- Typ transmisji na żywo lub VOD
- Format strumienia HLS lub DASH
- typ używanego odtwarzacza;
- Typ używanego backendu DAI
Format strumienia HLS (strumienie na żywo i VOD, odtwarzacz HLS.js)
Jeśli korzystasz z odtwarzacza HLS.js, posłuchaj
w zdarzeniu FRAG_PARSING_METADATA HLS.js, by pobrać metadane ID3 i przekazać je do
Pakiet SDK z StreamManager.processMetadata().
Aby automatycznie odtworzyć film, gdy wszystko będzie wczytane i gotowe, posłuchaj:
zdarzenie MANIFEST_PARSED HLS.js, które aktywuje odtwarzanie.
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 (format strumieni DASH oraz typ strumienia Na żywo i VOD)
Jeśli korzystasz z odtwarzacza DASH.js, musisz użyć różnych ciągów znaków, aby nasłuchiwać metadanych ID3 w przypadku transmisji na żywo lub VOD. strumienie:
- Transmisje na żywo:
'https://developer.apple.com/streaming/emsg-id3' - Strumienie VOD:
'urn:google:dai:2018'
Przekaż metadane ID3 do pakietu SDK za pomocą StreamManager.processMetadata().
Aby automatycznie wyświetlać elementy sterujące odtwarzaniem po załadowaniu wszystkich elementów:
nasłuchuje zdarzenia MANIFEST_LOADED DASH.js.
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 z transmisjami na żywo (format DASH)
Jeśli używasz odtwarzacza Shaki do
odtwarzania na żywo, użyj ciągu 'emsg', aby nasłuchiwać zdarzeń metadanych.
Następnie użyj danych komunikatu o zdarzeniu w wywołaniu pod numerem 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});
}
Odtwarzacz Shaka ze strumieniami VOD (format strumieni DASH)
Jeśli używasz odtwarzacza Shaki do
Odtwarzanie strumienia VOD, aby nasłuchiwać, użyj ciągu 'timelineregionenter'
zdarzenia związane z metadanymi. Następnie użyj danych komunikatu o zdarzeniu w rozmowie,
StreamManager.processMetadata()
ciągiem '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);
}
}