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 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 à une application de lecteur vidéo. Si vous souhaitez consulter 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 de flux en direct spécifient une clé d'élément, tandis que les requêtes de VOD spécifient un ID de CMS et un ID de 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 pour que le SDK IMA gère les identifiants des annonces, comme indiqué 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 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

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. 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 coupures publicitaires 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';
}
dai.js

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.

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

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 DAI. Le constructeur prend 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);
}
dai.js

Envoyer une requête de streaming

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 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 la section Authentifier les demandes de flux vidéo d'insertion dynamique d'annonce. Aucun des flux de cet exemple n'est protégé à l'aide d'une clé d'authentification pour l'insertion dynamique d'annonces. apiKey n'est donc pas utilisé.

Analyser les métadonnées du flux (diffusion en direct uniquement)

Pour les diffusions en direct, vous devez également ajouter un gestionnaire pour écouter les événements de métadonnées temporelles et les transmettre à la classe StreamManager afin qu'IMA émette des événements publicitaires pendant les coupures publicitaires:

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Only used in LIVE streams. 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 en streaming, 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 de l'annonce, ce que le SDK IMA nécessite.

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