Premiers pas avec le SDK IMA DAI

Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et applications. Les SDK IMA peuvent demander des annonces à n'importe quel ad server compatible avec VAST et gérer la lecture des annonces dans vos applications. Avec les SDK IMA pour l'insertion dynamique d'annonce, les applications envoient une demande de flux pour l'annonce et le contenu vidéo (VOD ou contenu en direct). Le SDK renvoie ensuite un flux vidéo combiné, ce qui vous évite d'avoir à gérer le basculement entre les annonces et les vidéos de contenu dans votre application.

Sélectionnez la solution d'insertion dynamique d'annonce qui vous intéresse.

Service complet Diffusion de pods

Insertion dynamique de séries d'annonces

Ce guide explique comment lire un flux d'insertion dynamique de séries d'annonces pour du contenu en direct ou de vidéo à la demande en utilisant le SDK IMA pour l'insertion dynamique d'annonce pour HTML5 avec un lecteur vidéo basé sur hls.js pour la lecture. Si vous souhaitez afficher ou suivre un exemple d'intégration terminé, compatible avec HLS.js et la lecture Safari, consultez l'exemple de diffusion de séries d'annonces HLS. Pour 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 sur la page GitHub des versions pour l'insertion dynamique d'annonces HTML5.

Remarque:Le SDK IMA pour l'insertion dynamique d'annonce pour HTML5 est compatible avec les flux HLS et DASH, mais la lecture de chacun d'eux nécessite un lecteur multimédia ou une extension différente, comme HLS.js ou DASH.js, avec des implémentations différentes.

Ce guide explique comment configurer le SDK HLS.js et le SDK IMA pour l'insertion dynamique d'annonce afin de lire un flux HLS. Il contient également des remarques importantes sur les différences d'implémentation pour DASH.

Consultez l'application exemple DASH.js IMA pour commencer à implémenter des flux d'insertion dynamique d'annonce DASH avec IMA.

Important :Pour utiliser l'insertion dynamique de séries d'annonces, vous devez collaborer avec un partenaire de diffusion de séries d'annonces et disposer d'un compte Ad Manager 360 avancé. Si vous possédez un compte Ad Manager, contactez votre responsable de compte pour en savoir plus. Pour en savoir plus sur l'inscription à Ad Manager, consultez le Centre d'aide Ad Manager.

Remarque:Pour en savoir plus sur l'intégration à d'autres plates-formes ou sur l'utilisation des SDK IMA côté client, consultez SDK Interactive Media Ads.

Présentation de l'insertion dynamique de séries d'annonces

L'implémentation de la diffusion de séries d'annonces à l'aide du SDK IMA DAI implique deux composants principaux, présentés dans ce guide:

• PodStreamRequest/PodVodStreamRequest: objet qui définit une requête de flux envoyée aux serveurs publicitaires de Google. Les requêtes spécifient un code de réseau, et le PodStreamRequest nécessite également une clé d'élément personnalisée et une clé API facultative. Tous deux incluent d'autres paramètres facultatifs.

• StreamManager: objet qui gère la communication entre le flux vidéo et le SDK IMA pour l'insertion dynamique d'annonce, comme le déclenchement des pings de suivi et 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 sur un serveur Web ou un autre environnement 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 à partir de laquelle il est chargé, vous devez utiliser un serveur Web pour tester votre application. Le moyen le plus simple de démarrer un serveur de développement local consiste à utiliser le serveur intégré de Python.

1. À l'aide d'une ligne de commande, exécutez la commande suivante à partir du répertoire contenant votre fichier index.html:

   python -m http.server 8000
   

   Remarque :http.server n'est disponible que dans Python 3.x.

2. Dans un navigateur Web, accédez à http://localhost:8000/

   Vous pouvez également utiliser n'importe quel autre environnement de développement ou serveur Web hébergé, tel que le serveur HTTP Apache.

Créer un lecteur vidéo simple

Remarque :Dans ce guide, nous partons du principe que vous utilisez la bibliothèque HLS.js pour lire un flux HLS. Le SDK IMA DAI pour HTML5 est également compatible avec les flux DASH, avec une bibliothèque appropriée comme le lecteur Shaka ou DASH.js.

Tout d'abord, modifiez dai.html pour créer un élément vidéo HTML5 simple et un tag div à utiliser pour les éléments de l'interface utilisateur des annonces. Ajoutez également les balises nécessaires pour charger les fichiers dai.css et dai.js, ainsi que pour importer le lecteur vidéo hls.js.

Ensuite, modifiez dai.css pour spécifier la taille et la position des éléments de la page. Enfin, dans dai.js, définissez des variables pour stocker les informations de la requête de flux et une fonction initPlayer() à exécuter lors du chargement de la page.

Les constantes des requêtes de flux sont les suivantes:

• BACKUP_STREAM: URL d'un flux secondaire à lire si le traitement des annonces rencontre une erreur fatale.

• STREAM_URL: utilisée uniquement pour les diffusions en direct. URL du flux vidéo fournie par votre outil de manipulation du fichier manifeste ou votre partenaire tiers utilisant la diffusion de séries d'annonces. Avant d'envoyer une demande, vous devez insérer l'ID de flux fourni par le SDK IMA pour l'insertion dynamique d'annonce. Dans ce cas, l'URL de flux inclut un espace réservé, [[STREAMID]], qui est remplacé par l'ID de flux avant d'envoyer une requête.

• NETWORK_CODE: code de réseau de votre compte Ad Manager 360.

• CUSTOM_ASSET_KEY: utilisée uniquement pour les diffusions en direct. Clé de l'élément personnalisé qui 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 de diffusion de pods tiers.

• API_KEY: utilisée uniquement pour les diffusions en direct. Une clé API facultative qui peut être requise pour récupérer un ID de flux à partir du SDK IMA pour l'insertion dynamique d'annonce.

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 dai.html, avant le tag pour dai.js.

Remarque :Pour recevoir des journaux de console plus détaillés, vous pouvez remplacer ima3_dai.js par ima3_dai_debug.js. Toutefois, ima3_dai_debug.js ne doit pas être utilisé dans les applications de production.

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 le StreamManager et envoyer une demande 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 sera chargé de demander et de gérer les flux d'insertion dynamique d'annonce. Le constructeur utilise un élément vidéo et l'instance résultante utilise un élément d'interface utilisateur d'annonce pour gérer les interactions avec les annonces.

Ensuite, définissez une fonction permettant de demander la diffusion en direct de la diffusion de séries d'annonces. Cette fonction crée d'abord un objet PodStreamRequest, le configure avec les paramètres de streamRequest fournis à l'étape 2, puis appelle streamManager.requestStream() avec cet objet de requête.

Important :Dans cet exemple, aucun des flux n'est protégé. apiKey n'est donc pas utilisé. Si votre flux nécessite une clé API, consultez la section Authentifier les requêtes de flux vidéo pour l'insertion dynamique d'annonce.

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 sera chargé de demander et de gérer les flux d'insertion dynamique d'annonce. Le constructeur utilise un élément vidéo et l'instance résultante utilise un élément d'interface utilisateur d'annonce pour gérer les interactions avec les annonces.

Ensuite, définissez une fonction pour demander le flux de VOD diffusant du pod. Cette fonction crée d'abord un objet PodVodStreamRequest, le configure avec les paramètres de 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 flux

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 événements STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED et AD_BREAK_ENDED en appelant une fonction onStreamEvent(). Cette fonction gère le chargement du flux et les erreurs, ainsi que la désactivation des commandes du lecteur pendant la lecture d'une annonce, comme l'exige le SDK. Une fois le flux chargé, le lecteur vidéo 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 événements STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED et AD_BREAK_ENDED en appelant une fonction onStreamEvent(). Cette fonction gère le chargement du flux et les erreurs, ainsi que la désactivation des commandes du lecteur pendant la lecture d'une annonce, ce qui est requis par le SDK.

De plus, les flux de diffusion de pods de VOD nécessitent d'appeler StreamManager.loadStreamMetadata() en réponse à l'événement STREAM_INITIALIZED. Vous devez également demander une URL de flux à votre partenaire VTP. Une fois l'appel loadStreamMetadata() réussi, il déclenche un événement LOADED, dans lequel vous devez appeler une fonction loadStream() avec votre URL de flux pour charger et lire le flux.

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 en fonction du format de flux (HLS ou DASH), du type de flux (flux en direct ou VOD), du type de lecteur et du type de backend d'insertion dynamique d'annonce utilisé. Pour en savoir plus, consultez notre guide sur les métadonnées temporelles.

Format de flux HLS (flux en direct et de vidéo à 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 transmettez-les 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 de 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 les flux en direct ou à la demande:

• 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, écoutez 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);
}

Shaka Player avec diffusions en direct (format de flux DASH)

Si vous utilisez le lecteur Shaka pour la lecture de flux 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 dans 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});
}

Shaka Player avec des flux de vidéo à la demande (format de flux DASH)

Si vous utilisez le lecteur Shaka pour la lecture de flux de vidéo à la demande, utilisez la chaîne 'timelineregionenter' pour écouter les événements de métadonnées. Utilisez ensuite les données du message d'événement dans votre appel à 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 du joueur

Ajoutez des écouteurs d'événements aux événements pause et start de l'élément vidéo pour permettre à l'utilisateur de reprendre la lecture lorsque le SDK s'interrompt 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 maintenant 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 les autres guides ou les exemples sur GitHub.