Premiers pas avec le SDK IMA DAI

Les SDK IMA permettent d'intégrer facilement des annonces multimédias à vos sites Web et applications. Les SDK IMA peuvent demander des annonces à n'importe quel ad server conforme à la norme VAST et gérer la lecture des annonces dans vos applications. Avec les SDK IMA DAI, les applications envoient une demande de flux pour les annonces et les vidéos de contenu (VOD ou contenu en direct). Le SDK renvoie ensuite un flux vidéo combiné, de sorte que vous n'ayez pas à gérer le basculement entre l'annonce et le contenu vidéo dans votre application.

Sélectionnez la solution de publicité display in-app qui vous intéresse.

Insertion dynamique d'annonces complète

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

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

L'implémentation du SDK IMA DAI implique deux composants principaux, comme indiqué dans ce guide:

  • StreamRequest : VODStreamRequest ou LiveStreamRequest : objet qui définit une requête de flux. Les demandes de flux peuvent concerner des vidéos à la demande ou des diffusions en direct. Les requêtes spécifient un ID de contenu, 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'annonces et les interactions avec le backend DAI. Le gestionnaire de flux gère également les pings de suivi et transfère les événements de flux et d'annonce à l'éditeur.

Prérequis

  • Trois fichiers vides
    • dai.html
    • dai.css
    • dai.js
  • Python installé sur votre ordinateur ou un serveur Web à utiliser pour les tests

Démarrer un serveur de développement

Étant donné que le SDK IMA DAI 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. Un moyen rapide 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

  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.

Créer un lecteur vidéo simple

Commencez par modifier dai.html pour créer un élément vidéo HTML5 simple et un élément div à utiliser pour le suivi des clics. 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 des variables pour contenir les informations de requête de flux et une 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 DAI 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'

// Livestream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2548831";
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');
}

Charger le SDK IMA DAI

Ajoutez ensuite le framework IMA à l'aide d'une balise de script dans dai.html, avant la balise 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 envoyer une requête de streaming

Pour demander un ensemble d'annonces, créez un ima.dai.api.StreamManager, qui est chargé de demander et de gérer les flux DAI. Le constructeur prend un élément vidéo et l'instance qui en résulte prend un élément d'UI d'annonce pour gérer les clics sur les annonces.

Définissez ensuite des fonctions qui demandent des flux. Cet exemple inclut des fonctions pour la VOD et les diffusions en direct, qui créent des instances de VODStreamRequest et de LiveStreamRequest, respectivement, 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ées et les transmettre à StreamManager. Vous pouvez commenter ou déscommenter le code en fonction de votre cas d'utilisation. Les deux méthodes acceptent une clé API facultative. Si vous utilisez un flux protégé, vous devez créer une clé d'authentification pour l'insertion dynamique d'annonce.

Aucun flux de cet exemple n'est protégé. apiKey n'est donc pas utilisé.

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);
}

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 et les erreurs du flux, ainsi que la désactivation des commandes du lecteur pendant la lecture d'une annonce, ce qui est requis par le SDK. Lorsque le flux est chargé, le lecteur vidéo charge et lit l'URL fournie à l'aide d'une fonction loadUrl().

Vous pouvez é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 est mis en pause pendant les coupures publicitaires.

Pour fonctionner avec l'insertion dynamique d'annonces, votre lecteur personnalisé doit transmettre des événements ID3 pour les diffusions en direct aux SDK IMA pour l'insertion dynamique d'annonces, comme indiqué dans l'exemple de code.

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 affichez désormais des annonces avec le SDK IMA DAI. Pour en savoir plus sur les fonctionnalités avancées du SDK, consultez les autres guides ou les exemples sur GitHub.