Configurer avec l'insertion dynamique d'annonces à service complet

Sélectionner une plate-forme : HTML5 Android iOS tvOS Cast Roku

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 sur GitHub.

Présentation de l'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 requêtes de flux peuvent concerner des flux de vidéo à la demande ou des flux en direct. Les demandes de diffusion 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 requêtes 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 permettant au SDK IMA de gérer les identifiants d'annonces 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 d'insertion dynamique d'annonces. Le gestionnaire de flux gère également les pings de suivi et transmet 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. Pour démarrer rapidement un serveur de développement local, vous pouvez 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

Commencez par modifier dai.html pour créer un élément vidéo HTML5 et un élément div à utiliser pour le clic. 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. 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 demande de flux, une fonction initPlayer() à exécuter lors du chargement de page, et configurez le bouton de lecture pour demander un flux au 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>


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

#adUi {
  cursor: pointer;
}

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

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

Pour reprendre la lecture pendant les coupures publicitaires mises en pause, 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';
}

Charger le SDK IMA DAI

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

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

Initialiser StreamManager

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'annonces. Le constructeur utilise un élément vidéo et un élément d'interface utilisateur 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);
}

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 de la classe VODStreamRequest et de la classe LiveStreamRequest. Une fois que vous disposez de 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);
}

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. Aucun des flux de cet exemple n'est protégé par une clé d'authentification DAI. 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'annonce pendant les coupures 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);
      });
    }
  });
}

Ce guide utilise le lecteur hls.js pour la lecture des flux, mais l'implémentation des 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 événements vidéo majeurs. 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 de l'annonce, 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();
  });
}

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

Et voilà ! Vous demandez et affichez désormais des annonces avec le SDK IMA DAI. Pour en savoir plus sur les fonctionnalités plus avancées du SDK, consultez les autres guides ou les exemples sur GitHub.