Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et applications. Les SDK IMA demander des annonces <ph type="x-smartling-placeholder"></ph> compatible avec la norme VAST et gérer la lecture des annonces dans vos applications. Avec les SDK IMA DAI, les applications demande de flux pour une annonce et du contenu vidéo (VOD ou en direct). Le SDK renvoie ensuite un flux vidéo combiné, pour vous éviter d'avoir à gérer le basculement entre l'annonce et la vidéo de contenu. dans votre application.
Sélectionnez la solution d'insertion dynamique d'annonce qui vous intéresse
Insertion dynamique de séries d'annonces
Ce guide explique comment lire un flux d'insertion dynamique de séries d'annonces en direct ou à la demande contenu, en utilisant le SDK IMA DAI pour HTML5 avec un lecteur vidéo basé sur hls.js pour la lecture. Si vous souhaitez consulter ou suivre un exemple terminé compatible avec HLS.js et la lecture dans Safari, consultez les Exemple de diffusion de pods HLS Pour en savoir plus sur la compatibilité avec DASH.js, consultez l'exemple de diffusion de séries d'annonces DASH. Vous pouvez télécharger ces exemples d'applications à partir de la version GitHub pour l'insertion dynamique d'annonce HTML5 .
Présentation de l'insertion dynamique de séries d'annonces
La mise en œuvre de la diffusion de séries d'annonces à l'aide du SDK IMA DAI implique deux composants principaux : présentées dans ce guide:
PodStreamRequest
/PodVodStreamRequest
: objet qui définit une requête de flux à serveurs publicitaires de Google. Les requêtes spécifient un code de réseau, et lePodStreamRequest
nécessite également une clé d'élément personnalisée et une clé Clé API : Tous deux incluent d'autres paramètres facultatifs.StreamManager
: objet qui gère la communication entre le flux vidéo et le SDK IMA DAI, comme le déclenchement de pings de suivi le transfert des événements de flux à l'éditeur.
Prérequis
Avant de commencer, vous avez besoin des éléments suivants :
Trois fichiers vides:
- dai.html
- dai.css
- dai.js
Python installé sur votre ordinateur, ou un serveur Web ou un autre outil de développement hébergé à utiliser pour les tests
Configurer un environnement de développement
Étant donné que le SDK charge les dépendances à l'aide du même protocole que la page du chargée, vous devez utiliser un serveur Web pour tester votre application. Quelques mots démarrer un serveur de développement local consiste à utiliser le serveur intégré de Python.
À l'aide d'une ligne de commande, à partir du répertoire contenant votre
index.html
exécution du fichier:python -m http.server 8000
Dans un navigateur Web, accédez à
http://localhost:8000/
.Vous pouvez également utiliser tout autre environnement de développement ou serveur Web hébergé, tel que en tant que serveur HTTP Apache.
Créer un lecteur vidéo simple
Modifiez d'abord le fichier dai.html pour créer un élément vidéo HTML5 simple et un tag div
pour les éléments de l'UI des annonces. Ajoutez également les balises nécessaires au chargement du fichier dai.css.
et dai.js, ainsi que pour importer le lecteur vidéo hls.js
.
Modifiez ensuite le fichier dai.css pour spécifier la taille et la position des éléments de la page.
Enfin, définissez des variables dans dai.js pour contenir les informations de la demande de flux.
et une fonction initPlayer()
à exécuter lors du chargement de la page.
Les constantes de requête de flux sont les suivantes:
BACKUP_STREAM
: URL d'un flux secondaire à lire si le processus d'annonces est en cours rencontre une erreur fatale.STREAM_URL
: utilisé uniquement pour les diffusions en direct URL du flux vidéo fournie par votre outil de manipulation du fichier manifeste ou votre partenaire tiers à l'aide de la diffusion de séries d'annonces. Il doit vous devez insérer l'ID de flux fourni par le SDK IMA DAI avant faire une demande. Dans ce cas, l'URL de flux comprend un espace réservé,[[STREAMID]]
, qui est remplacé par l'ID de flux avant d'envoyer une demande.NETWORK_CODE
: code de réseau de votre compte Ad Manager 360.CUSTOM_ASSET_KEY
: utilisé uniquement pour les diffusions en direct La clé de l'élément personnalisé identifie l'événement de diffusion de séries d'annonces dans Ad Manager 360. Il peut être créé par votre outil de manipulation du fichier manifeste ou votre partenaire tiers de diffusion de séries d'annonces.API_KEY
: utilisé uniquement pour les diffusions en direct Une clé API facultative pouvant être pour récupérer un ID de flux à partir du SDK IMA DAI.
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');
}
Charger le SDK IMA DAI
Ajoutez ensuite le framework d'insertion dynamique d'annonce à l'aide d'un tag de script dans le fichier dai.html, avant le tag. pour 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>
...
Initialiser StreamManager et effectuer une requête de flux en direct ou de vidéo à la demande
Diffusion de séries d'annonces en direct
Pour demander un ensemble d'annonces, créez un ima.dai.api.StreamManager
, qui
est responsable de la demande et de la gestion des flux pour l'insertion dynamique d'annonce. Le constructeur utilise
d'un élément vidéo. L'instance qui en résulte utilise un élément d'UI d'annonce pour gérer l'annonce
des interactions.
Ensuite, définissez une fonction pour demander la diffusion en direct de la diffusion de pods. Cette fonction
crée d'abord un PodStreamRequest
, le configure avec le paramètre "streamRequest"
fournis à l'étape 2, puis appelle streamManager.requestStream()
avec cet objet de requête.
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);
}
Diffusion de séries d'annonces VOD
Pour demander un ensemble d'annonces, créez un ima.dai.api.StreamManager
, qui
est responsable de la demande et de la gestion des flux pour l'insertion dynamique d'annonce. Le constructeur utilise
d'un élément vidéo. L'instance qui en résulte utilise un élément d'UI d'annonce pour gérer l'annonce
des interactions.
Ensuite, définissez une fonction pour demander le flux VOD de diffusion de séries d'annonces. Cette fonction
crée d'abord un PodVodStreamRequest
, le configure avec le paramètre "streamRequest"
fournis à l'étape 2, puis appelle streamManager.requestStream()
avec cet objet de requête.
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);
}
Gérer les événements de diffusion
Diffusion de séries d'annonces en direct
Implémentez ensuite des écouteurs d'événements pour les événements vidéo majeurs. Cet exemple gère
les éléments STREAM_INITIALIZED
, ERROR
, AD_BREAK_STARTED
et AD_BREAK_ENDED
des événements en appelant une fonction onStreamEvent()
. Cette fonction gère les flux
chargements et erreurs, ainsi que la désactivation des commandes du lecteur lorsqu'une annonce
requis par le SDK. Une fois le flux chargé, la vidéo
Le lecteur charge et lit l'URL fournie à l'aide d'une fonction 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);
}
Diffusion de séries d'annonces VOD
Implémentez ensuite des écouteurs d'événements pour les événements vidéo majeurs. Cet exemple gère
les éléments STREAM_INITIALIZED
, LOADED
, ERROR
, AD_BREAK_STARTED
et
AD_BREAK_ENDED
en appelant une fonction onStreamEvent()
. Ce
gère le chargement du flux et les erreurs, ainsi que la désactivation du lecteur.
pendant la lecture d'une annonce, ce qui est requis par le SDK.
De plus, les flux de diffusion de séries d'annonces VOD nécessitent l'appel
StreamManager.loadStreamMetadata()
en réponse à la
STREAM_INITIALIZED
. Vous devez également demander une URL de flux à partir de votre
un partenaire technologique vidéo (VTP). Une fois l'appel loadStreamMetadata()
réussi
elle déclenche un événement LOADED
, dans lequel vous devez appeler une fonction loadStream()
.
avec l'URL de votre flux pour le charger et le lire.
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);
}
Gérer les métadonnées de flux
Au cours de cette étape, vous allez implémenter des écouteurs d'événements pour les métadonnées afin d'informer le SDK lorsque des événements d'annonce se produisent. L'écoute des événements de métadonnées InStream peut varier le format du flux (HLS ou DASH), le type de flux (flux en direct ou à la demande), votre le type de joueur et le type de backend d'insertion dynamique d'annonce utilisé. Consultez notre Métadonnées .
Format de flux HLS (flux en direct et à la demande, lecteur HLS.js)
Si vous utilisez un lecteur HLS.js, écoutez
l'événement HLS.js FRAG_PARSING_METADATA
pour obtenir les métadonnées ID3 et les transmettre au
SDK avec StreamManager.processMetadata()
.
Pour lire automatiquement la vidéo une fois que tout est chargé et prêt, écoutez
l'événement MANIFEST_PARSED
HLS.js pour déclencher la lecture ;
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 de flux DASH, type de flux en direct et vidéo à la demande)
Si vous utilisez un lecteur DASH.js, vous devez utiliser des chaînes différentes pour écouter les métadonnées ID3 pour le direct ou la vidéo à la demande. flux:
- Diffusions en direct:
'https://developer.apple.com/streaming/emsg-id3'
- Flux de vidéo à la demande:
'urn:google:dai:2018'
Transmettez les métadonnées ID3 au SDK avec StreamManager.processMetadata()
.
Pour afficher automatiquement les commandes vidéo une fois que tout est chargé et prêt,
écouter l'événement 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);
}
Lecteur Shaka avec diffusions en direct (format de flux DASH)
Si vous utilisez le lecteur Shaka pour
diffusion en direct, utilisez la chaîne 'emsg'
pour écouter les événements de métadonnées.
Utilisez ensuite les données du message d'événement de votre appel à 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});
}
Lecteur Shaka avec flux de vidéo à la demande (format de flux DASH)
Si vous utilisez le lecteur Shaka pour
la lecture d'un flux VOD. Utilisez la chaîne 'timelineregionenter'
pour l'écouter ;
des événements de métadonnées. Utilisez ensuite les données du message d'événement de votre appel pour
StreamManager.processMetadata()
avec la chaîne '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);
}
}
Gérer les événements de joueur
Ajoutez des écouteurs d'événements aux événements pause
et start
de l'élément vidéo pour autoriser
à l'utilisateur de reprendre la lecture
lorsque le SDK se met en pause pendant les coupures publicitaires.
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';
}
}
Et voilà ! Vous demandez et affichez à présent des annonces dans un flux de diffusion de séries d'annonces avec le SDK IMA DAI pour HTML5. Pour en savoir plus sur les fonctionnalités avancées du SDK, consultez d'autres guides ou les exemples sur GitHub