Configurer le SDK IMA pour l'insertion dynamique d'annonces

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 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 vidéos d'annonces et de contenu dans votre application.

Sélectionnez la solution DAI qui vous intéresse.

Insertion dynamique d'annonces (service complet)

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

Présentation d'IMA DAI

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 demandes de flux en direct spécifient une clé d'élément, tandis que les demandes de VOD spécifient un ID CMS et un ID vidéo. Les deux types de demandes peuvent éventuellement inclure une clé API nécessaire pour accéder aux flux spécifiés, ainsi qu'un code de réseau Google Ad Manager pour que le SDK IMA gère les identifiants publicitaires comme spécifié dans les paramètres Google Ad Manager.
  • 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 transmet les événements de flux et d'annonces à 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 depuis le 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, comme le serveur HTTP Apache.

Créer un lecteur vidéo

Commencez par modifier dai.html pour créer un élément vidéo HTML5 et un div à utiliser pour le clickthrough. L'exemple suivant importe le SDK IMA DAI. Pour en savoir plus, consultez Importer le SDK IMA DAI.

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 la requête de flux, une fonction initPlayer() à exécuter lorsque la page se charge et configurez le bouton de lecture pour demander un flux en cas de clic.

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>


dai.html
 
#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}

dai.css
 
// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}
dai.js

Pour reprendre la lecture pendant les pauses publicitaires, configurez des écouteurs d'événements pour les événements pause et start de l'élément vidéo afin d'afficher et de masquer les commandes du lecteur.

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}
dai.js

Charger le SDK IMA DAI

Ensuite, ajoutez le framework IMA à l'aide d'une balise de script dans dai.html, avant la balise pour dai.js.

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
dai.html

Initialiser le StreamManager

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 d'insertion dynamique d'annonces. Le constructeur prend un élément vidéo et un élément d'UI d'annonce pour gérer les clics sur les annonces.

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}
dai.js

Envoyer une requête de flux

Définissez des fonctions pour demander des flux. Cet exemple inclut des fonctions pour la VOD et les diffusions en direct, qui créent des instances des classes VODStreamRequest et LiveStreamRequest. Une fois que vous avez votre instance streamRequest, appelez la méthode streamManager.requestStream() avec l'instance de requête de flux.

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}
dai.js

Les deux méthodes de requête de flux 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'annonces. Pour en savoir plus, consultez Authentifier les demandes de flux vidéo d'insertion dynamique d'annonce. Dans cet exemple, aucun flux n'est protégé à l'aide d'une clé d'authentification pour l'insertion dynamique d'annonce. Par conséquent, apiKey n'est pas utilisé.

Analyser les métadonnées du flux

Vous devez également ajouter un gestionnaire pour écouter les événements de métadonnées temporelles et les transférer à la classe StreamManager afin qu'IMA émette des événements d'annonces pendant les breaks publicitaires :

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Timed metadata is handled differently by different video players, and the
  // IMA SDK provides two ways to pass in metadata,
  // StreamManager.processMetadata() and StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we 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);
      });
    }
  });
}
dai.js

Ce guide utilise le lecteur hls.js pour la lecture des flux, mais l'implémentation de vos métadonnées dépend du type de lecteur que vous utilisez.

Gérer les événements de flux

Implémentez des écouteurs d'événements pour les principaux événements vidéo. Cet exemple 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 du flux, les erreurs de flux et la désactivation des commandes du lecteur pendant la lecture des annonces, ce qui est requis par le SDK IMA.

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
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');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
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();
  });
}
dai.js

Lorsque le flux est chargé, le lecteur vidéo charge et lit l'URL fournie à l'aide d'une fonction loadUrl().

Et voilà ! Vous demandez et diffusez 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.