Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą wysyłać żądania reklam z dowolnego serwera reklam zgodnego z VAST i zarządzać odtwarzaniem reklam w aplikacjach. Dzięki pakietom SDK IMA DAI aplikacje wysyłają żądania strumienia danych wideo z reklam i treści wideo – VOD lub treści na żywo. Pakiet SDK zwraca połączony strumień wideo, więc nie musisz już zarządzać przełączaniem się między reklamą a treścią wideo w aplikacji.
Wybierz rozwiązanie DAI, które Cię interesuje
Blok reklamowy z dynamicznym wstawianiem reklam
Ten przewodnik pokazuje, jak odtwarzać strumień wyświetlania podów z dynamicznym wstawianiem reklam w przypadku treści na żywo lub VOD za pomocą pakietu IMA DAI SDK na potrzeby HTML5 i odtwarzacza wideo, który korzysta z kodu hls.js. Jeśli chcesz zobaczyć ukończoną integrację przykładową z obsługą zarówno HLS.js, jak i odtwarzania w Safari, zapoznaj się z przykładem obsługi bloków reklamowych HLS. Informacje o obsłudze DASH.js znajdziesz w przykładzie wyświetlania bloków reklamowych DASH. Te przykładowe aplikacje możesz pobrać ze strony wersji HTML5 DAI na GitHubie.
Omówienie wyświetlania podów z dynamicznym wstawianiem reklam
Implementacja wyświetlania bloków reklamowych za pomocą pakietu IMA DAI SDK obejmuje 2 główne komponenty, które przedstawiamy w tym przewodniku:
PodStreamRequest
/PodVodStreamRequest
: obiekt definiujący żądanie strumienia do serwerów reklamowych Google. Żądania określają kod sieci, aPodStreamRequest
wymaga też niestandardowego klucza zasobu i opcjonalnego klucza interfejsu API. Oba typy zawierają inne opcjonalne parametry.StreamManager
: obiekt obsługujący komunikację między strumieniem wideo a pakietem IMA DAI SDK, np. uruchamianie pingów śledzących i przekierowywanie zdarzeń strumienia do wydawcy.
Wymagania wstępne
Zanim zaczniesz, musisz mieć:
Trzy puste pliki:
- dai.html
- dai.css
- dai.js
Python zainstalowany na komputerze, serwer WWW lub inne hostowane środowisko programistyczne do testowania
Konfigurowanie środowiska programistycznego
Pakiet SDK wczytuje zależności za pomocą tego samego protokołu co strona, z której jest wczytywana, dlatego do przetestowania aplikacji musisz użyć serwera WWW. Szybkim sposobem na uruchomienie lokalnego serwera programistycznego jest użycie wbudowanego serwera Pythona.
Za pomocą wiersza poleceń, z katalogu zawierającego uruchomienie pliku
index.html
:python -m http.server 8000
W przeglądarce otwórz stronę
http://localhost:8000/
Możesz też używać dowolnego innego hostowanego środowiska programistycznego lub serwera WWW, na przykład serwera HTTP Apache.
Utwórz prosty odtwarzacz wideo
Najpierw zmodyfikuj dai.html, by utworzyć prosty element wideo HTML5 i element div do użycia z elementami interfejsu reklamy. Dodaj też tagi potrzebne do wczytania plików dai.css i dai.js oraz do zaimportowania odtwarzacza wideo hls.js
.
Następnie zmodyfikuj plik dai.css, by określić rozmiar i pozycję elementów strony.
Na koniec w pliku dai.js zdefiniuj zmienne, które będą przechowywać informacje o żądaniu strumienia, oraz funkcję initPlayer()
, która ma być uruchamiana po wczytaniu strony.
Stałe żądania strumienia są następujące:
BACKUP_STREAM
: adres URL strumienia zapasowego, który będzie odtwarzany na wypadek wystąpienia błędu krytycznego w procesie wyświetlania reklam.STREAM_URL
: używany tylko w przypadku transmisji na żywo. Adres URL strumienia wideo podany przez manipulator pliku manifestu lub partnera zewnętrznego, który korzysta z bloków reklamowych. Przed wysłaniem żądania powinno być wymagane wstawienie identyfikatora strumienia dostarczonego przez pakiet IMA DAI SDK. W tym przypadku adres URL strumienia zawiera obiekt zastępczy[[STREAMID]]
, który przed wysłaniem żądania jest zastępowany identyfikatorem strumienia.NETWORK_CODE
: kod sieci Twojego konta Ad Managera 360.CUSTOM_ASSET_KEY
: używany tylko w przypadku transmisji na żywo. Niestandardowy klucz pliku identyfikujący zdarzenie wyświetlania bloku reklamowego w usłudze Ad Manager 360. Można go utworzyć za pomocą manipulatora pliku manifestu lub zewnętrznego partnera obsługującego pody.API_KEY
: używany tylko w przypadku transmisji na żywo. Opcjonalny klucz interfejsu API, który może być wymagany do pobrania identyfikatora strumienia z pakietu IMA DAI SDK.
dai.html
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<script src="dai.js"></script>
<link rel="stylesheet" href="dai.css" type="text/css">
</head>
<body onLoad="initPlayer()">
<h2>IMA DAI SDK Demo (HLS.JS)</h2>
<video id="video"></video>
<div id="ad-ui"></div>
</body>
</html>
dai.css
#video,
#ad-ui {
width: 640px;
height: 360px;
position: absolute;
top: 35px;
left: 0;
}
#ad-ui {
cursor: pointer;
}
dai.js
var BACKUP_STREAM =
'https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8'
// Stream Config.
const STREAM_URL = "https://encodersim.sandbox.google.com/masterPlaylist/...&stream_id=[[STREAMID]]";
const NETWORK_CODE = "51636543";
const CUSTOM_ASSET_KEY = "google-sample";
const API_KEY = "";
var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
}
Wczytaj pakiet IMA DAI SDK
Następnie dodaj platformę DAI za pomocą tagu skryptu w pliku dai.html przed tagiem dai.js.
dai.html
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
<script src="dai.js"></script>
<link rel="stylesheet" href="dai.css" type="text/css">
</head>
...
Zainicjuj usługę StreamManager i wyślij żądanie strumienia na żywo lub VOD
Blok reklamowy w transmisjach na żywo
Aby poprosić o zestaw reklam, utwórz ima.dai.api.StreamManager
, który odpowiada za wysyłanie żądań strumieni DAI i zarządzanie nimi. Konstruktor pobiera element wideo, a wystąpienie go wykorzystuje element interfejsu reklamy do obsługi interakcji z reklamą.
Następnie zdefiniuj funkcję, która wysyła żądanie bloku reklamowego do transmisji na żywo. Ta funkcja najpierw tworzy obiekt PodStreamRequest
, konfiguruje go za pomocą parametrów streamRequest podanych w kroku 2, a potem wywołuje streamManager.requestStream()
za pomocą tego obiektu żądania.
dai.js
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)
requestLivePodStream(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
}
function requestLivePodStream(networkCode, customAssetKey, apiKey) {
// clear HLS.js instance, if in use
if (hls) {
hls.destroy();
}
// Generate a Pod Serving live Stream Request
const streamRequest = new google.ima.dai.api.PodStreamRequest();
streamRequest.networkCode = networkCode;
streamRequest.customAssetKey = customAssetKey;
streamRequest.apiKey = apiKey;
streamRequest.format = 'hls';
streamManager.requestStream(streamRequest);
}
Wyświetlanie bloków reklamowych VOD
Aby poprosić o zestaw reklam, utwórz ima.dai.api.StreamManager
, który odpowiada za wysyłanie żądań strumieni DAI i zarządzanie nimi. Konstruktor pobiera element wideo, a wystąpienie go wykorzystuje element interfejsu reklamy do obsługi interakcji z reklamą.
Następnie zdefiniuj funkcję, która wysyła żądanie poda obsługującego strumień VOD. Ta funkcja najpierw tworzy obiekt PodVodStreamRequest
, konfiguruje go za pomocą parametrów streamRequest podanych w kroku 2, a potem wywołuje streamManager.requestStream()
za pomocą tego obiektu żądania.
dai.js
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)
requestVodPodStream(NETWORK_CODE);
}
function requestVodPodStream(networkCode) {
// clear HLS.js instance, if in use
if (hls) {
hls.destroy();
}
// Generate a Pod Serving VOD Stream Request
const streamRequest = new google.ima.dai.api.PodVodStreamRequest();
streamRequest.networkCode = networkCode;
streamRequest.format = 'hls';
streamManager.requestStream(streamRequest);
}
Obsługuj zdarzenia strumienia
Blok reklamowy w transmisjach na żywo
Następnie zaimplementuj detektory ważnych zdarzeń wideo. W tym przykładzie obsługujemy zdarzenia STREAM_INITIALIZED
, ERROR
, AD_BREAK_STARTED
i AD_BREAK_ENDED
przez wywołanie funkcji onStreamEvent()
. Ta funkcja obsługuje wczytywanie strumienia i błędami, a także wyłączanie elementów sterujących odtwarzaczem podczas odtwarzania reklamy (jest to wymagane przez pakiet SDK). Po wczytaniu strumienia odtwarzacz wczytuje i odtwarza podany adres URL za pomocą funkcji loadStream()
.
dai.js
var isAdBreak;
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
streamManager.addEventListener(
[google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
google.ima.dai.api.StreamEvent.Type.ERROR,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
onStreamEvent,
false);
...
function onStreamEvent(e) {
switch (e.type) {
case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
console.log('Stream initialized');
loadStream(e.getStreamData().streamId);
break;
case google.ima.dai.api.StreamEvent.Type.ERROR:
console.log('Error loading stream, playing backup stream.' + e);
loadStream('');
break;
case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
console.log('Ad Break Started');
isAdBreak = true;
videoElement.controls = false;
adUiElement.style.display = 'block';
break;
case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
console.log('Ad Break Ended');
isAdBreak = false;
videoElement.controls = true;
adUiElement.style.display = 'none';
break;
default:
break;
}
}
function loadStream(streamID) {
var url;
if(streamID) {
url = STREAM_URL.replace('[[STREAMID]]', streamID);
} else {
console.log('Stream Initialization Failed');
url = BACKUP_STREAM;
}
console.log('Loading:' + url);
hls.loadSource(url);
hls.attachMedia(videoElement);
}
Wyświetlanie bloków reklamowych VOD
Następnie zaimplementuj detektory ważnych zdarzeń wideo. W tym przykładzie obsługujemy zdarzenia STREAM_INITIALIZED
, LOADED
, ERROR
, AD_BREAK_STARTED
i AD_BREAK_ENDED
przez wywołanie funkcji onStreamEvent()
. Ta funkcja obsługuje wczytywanie strumienia i błędami, a także wyłączanie elementów sterujących odtwarzaczem podczas odtwarzania reklamy (jest to wymagane przez pakiet SDK).
Dodatkowo strumienie wyświetlania bloków reklamowych VOD wymagają wywołania StreamManager.loadStreamMetadata()
w odpowiedzi na zdarzenie STREAM_INITIALIZED
. Musisz też poprosić partnera ds. technologii wideo o adres URL transmisji. Po pomyślnym wywołaniu loadStreamMetadata()
aktywuje zdarzenie LOADED
. W tym celu należy wywołać funkcję loadStream()
z adresem URL strumienia, aby wczytać i odtworzyć strumień.
var isAdBreak;
function initPlayer() {
videoElement = document.getElementById('video');
adUiElement = document.getElementById('adUi');
streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
streamManager.addEventListener(
[google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
google.ima.dai.api.StreamEvent.Type.ERROR,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
onStreamEvent,
false);
...
function onStreamEvent(e) {
switch (e.type) {
case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
const streamId = e.getStreamData().streamId;
// 'vtpInterface' is a place holder for your own video technology
// partner (VTP) API calls.
vtpInterface.requestStreamURL({
'streamId': streamId,
})
.then( (vtpStreamUrl) => {
streamUrl = vtpStreamUrl;
streamManager.loadStreamMetadata();
}, (error) => {
// Handle the error.
});
break;
case google.ima.dai.api.StreamEvent.Type.LOADED:
loadStream(streamUrl);
break;
case google.ima.dai.api.StreamEvent.Type.ERROR:
console.log('Error loading stream, playing backup stream.' + e);
loadStream();
break;
case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
console.log('Ad Break Started');
isAdBreak = true;
videoElement.controls = false;
adUiElement.style.display = 'block';
break;
case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
console.log('Ad Break Ended');
isAdBreak = false;
videoElement.controls = true;
adUiElement.style.display = 'none';
break;
default:
break;
}
}
function loadStream(url) {
if(url) {
console.log('Loading:' + url);
hls.loadSource(url);
} else {
console.log('Stream Initialization Failed');
hls.loadSource(BACKUP_STREAM);
}
hls.attachMedia(videoElement);
}
Obsługa metadanych strumienia
W tym kroku wdrożysz detektory zdarzeń metadanych, aby powiadamiały pakiet SDK o wystąpieniu zdarzeń reklamowych. Nasłuchiwanie zdarzeń metadanych In-Stream może się różnić w zależności od formatu strumienia (HLS lub DASH), typu strumienia (na żywo lub VOD), typu odtwarzacza i typu używanego backendu DAI. Więcej informacji znajdziesz w przewodniku po metadanych z sygnaturą czasową.
Format strumienia HLS (strumienie na żywo i VOD, odtwarzacz HLS.js)
Jeśli korzystasz z odtwarzacza HLS.js, nasłuchuj zdarzenia FRAG_PARSING_METADATA
HLS.js, aby uzyskać metadane ID3 i przekazać je do pakietu SDK z StreamManager.processMetadata()
.
Aby automatycznie odtworzyć film, gdy wszystko zostanie wczytane i gotowe, nasłuchuj zdarzenia MANIFEST_PARSED
HLS.js, co 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żeli korzystasz z odtwarzacza DASH.js, musisz użyć różnych ciągów do nasłuchiwania metadanych ID3 w przypadku strumieni na żywo lub VOD:
- 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 filmem, gdy wszystkie elementy zostaną wczytane i gotowe, posłuchaj 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żeli do odtwarzania transmisji na żywo używasz odtwarzacza Shasha, do nasłuchiwania zdarzeń metadanych użyj ciągu 'emsg'
.
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żeli do odtwarzania strumienia VOD korzystasz z odtwarzacza Shasha, użyj ciągu 'timelineregionenter'
, aby nasłuchiwać zdarzeń metadanych. Następnie użyj danych komunikatu o zdarzeniu w wywołaniu funkcji StreamManager.processMetadata()
z ciągiem znaków '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);
}
}
Obsługa zdarzeń graczy
Dodaj detektory zdarzeń do zdarzeń pause
i start
elementu wideo, aby umożliwić użytkownikowi wznawianie odtwarzania, gdy pakiet SDK jest wstrzymany podczas przerw na reklamę.
function loadStream(streamUrl) {
...
videoElement.addEventListener('pause', onStreamPause);
videoElement.addEventListener('play', onStreamPlay);
}
function onStreamPause() {
console.log('paused');
if (isAdBreak) {
videoElement.controls = true;
adUiElement.style.display = 'none';
}
}
function onStreamPlay() {
console.log('played');
if (isAdBreak) {
videoElement.controls = false;
adUiElement.style.display = 'block';
}
}
Znakomicie. Za pomocą pakietu IMA DAI SDK dla HTML5 wysyłasz żądania i wyświetlasz reklamy w strumieniu wyświetlania reklam w bloku reklamowym. Więcej informacji o bardziej zaawansowanych funkcjach pakietu SDK znajdziesz w innych przewodnikach lub na przykładach w serwisie GitHub.