Commencer

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

Ce guide explique comment intégrer le SDK IMA à une application de lecteur vidéo simple. Si vous souhaitez afficher ou suivre un exemple d'intégration terminé, téléchargez l'exemple simple depuis GitHub.

Présentation de l'insertion dynamique d'annonce IMA

La mise en œuvre de l'insertion dynamique d'annonce IMA implique deux composants principaux du SDK, comme indiqué dans ce guide:

  • StreamRequest ( VODStreamRequest ou LiveStreamRequest) : objet qui définit une requête de flux. Il peut s'agir de vidéos à la demande ou de diffusions en direct. Les requêtes spécifient un Content ID, ainsi qu'une clé API ou un jeton d'authentification, ainsi que d'autres paramètres.
  • StreamManager : objet qui gère les flux d'insertion dynamique d'annonce et les interactions avec le backend d'insertion dynamique d'annonce. Le gestionnaire de flux gère également le suivi des pings et transmet les événements de flux et d'annonce à l'éditeur.

Conditions préalables

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 à utiliser pour les tests

1. Démarrer un serveur de développement

Étant donné que le SDK IMA charge les dépendances via le 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, dans le répertoire contenant votre fichier index.html, exécutez la commande suivante:

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

Vous pouvez également utiliser n'importe quel autre serveur Web, tel que le serveur HTTP Apache.

2. Créer un lecteur vidéo simple

Modifiez d'abord dai.html pour créer un élément vidéo HTML5 simple et un élément div pour le clic. 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. Modifiez ensuite dai.css pour spécifier la taille et la position des éléments de la page. Enfin, dans dai.js, définissez les variables qui contiennent les informations de requête de flux et la fonction initPlayer() à exécuter lors du chargement de la page.

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 SDK DAI 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'

// Live stream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2528370";
var TEST_VIDEO_ID = "tears-of-steel";

var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;
var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
}

3. Charger le SDK IMA

Ensuite, ajoutez le framework IMA à l'aide d'un tag de script dans dai.html, avant le tag 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>

...

4. Initialiser StreamManager et effectuer une requête de flux

Pour demander un ensemble d'annonces, créez un ima.dai.api.StreamManager qui est 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 obtenue utilise un élément d'interface utilisateur d'annonce pour gérer les clics.

Ensuite, définissez des fonctions qui demandent des flux. Cet exemple inclut des fonctions pour les flux de vidéo à la demande et en direct, qui créent respectivement des instances de VODStreamRequest et LiveStreamRequest, puis appellent streamManager.requestStream() avec les paramètres streamRequest. Pour les diffusions en direct, vous devez également ajouter un gestionnaire pour écouter les événements de métadonnées temporisés et les transférer vers StreamManager. Vous pouvez commenter le code ou annuler sa mise en commentaire pour l'adapter à votre cas d'utilisation. Les deux méthodes utilisent une clé API facultative. Si vous utilisez un flux chiffré, vous devez créer une clé d'authentification 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)

  // Timed metadata is only used for LIVE streams.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(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(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });

  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, null);
  // Uncomment the line below and comment out the one above to request a
  // LIVE stream instead of a VOD stream.
  //requestLiveStream(TEST_ASSET_KEY, null);
}

function requestVODStream(cmsId, videoId, apiKey) {
  var streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

function requestLiveStream(assetKey, apiKey) {
  var streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

5. Gérer les événements de flux

Enfin, vous devez implémenter des écouteurs d'événements pour les principaux événements vidéo. Cet exemple simple gère les événements LOADED, ERROR, AD_BREAK_STARTED et AD_BREAK_ENDED en appelant une fonction onStreamEvent(). Cette fonction gère le chargement de flux et les erreurs, et désactive les commandes du lecteur pendant la lecture d'une annonce, comme requis par le SDK. Une fois le flux chargé, le lecteur vidéo charge et lit l'URL fournie à l'aide d'une fonction loadUrl().

Vous devez également configurer des écouteurs d'événements pour les événements pause et start de l'élément vidéo afin de permettre à l'utilisateur de reprendre la lecture lorsque l'IMA s'interrompt pendant les coupures publicitaires.

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);

  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.LOADED,
     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.LOADED:
      console.log('Stream loaded');
      loadUrl(e.getStreamData().url);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadUrl(BACKUP_STREAM);
      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 loadUrl(url) {
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  hls.on(Hls.Events.MANIFEST_PARSED, function() {
    console.log('Video Play');
    videoElement.play();
  });
}

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 diffusez maintenant des annonces avec le SDK IMA. Pour découvrir d'autres fonctionnalités avancées du SDK, consultez les autres guides ou les exemples sur GitHub.