Configurer le SDK IMA

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 côté client IMA, vous gardez le contrôle de la lecture du contenu vidéo, tandis que le SDK gère la lecture des annonces. Les annonces sont diffusées dans un lecteur vidéo distinct situé au-dessus du lecteur vidéo de contenu de l'application.

Ce guide explique comment intégrer le SDK IMA dans une application de lecteur vidéo simple. Si vous souhaitez voir ou suivre un exemple d'intégration terminée, téléchargez l'exemple simple sur GitHub. Si vous souhaitez utiliser un lecteur HTML5 avec le SDK préintégré, consultez le plug-in du SDK IMA pour Video.js.

Présentation de l'IMA côté client

L'implémentation d'IMA côté client implique quatre composants principaux du SDK, qui sont illustrés dans ce guide:

  • AdDisplayContainer : objet de conteneur qui spécifie où IMA affiche les éléments d'interface utilisateur de l'annonce et mesure la visibilité, y compris Active View et Open Measurement.
  • AdsLoader : objet qui demande des annonces et gère les événements à partir des réponses aux requêtes d'annonces. Vous ne devez instancier qu'un seul chargeur d'annonces, qui peut être réutilisé tout au long de la durée de vie de l'application.
  • AdsRequest : objet qui définit une requête d'annonces. Les requêtes d'annonces spécifient l'URL du tag d'emplacement publicitaire VAST, ainsi que des paramètres supplémentaires, tels que les dimensions de l'annonce.
  • AdsManager : objet contenant la réponse à la demande d'annonces, qui contrôle la lecture des annonces et qui écoute les événements d'annonces déclenchés par le SDK.

Prérequis

Avant de commencer, vous aurez besoin des éléments suivants :

  • Trois fichiers vides :
    • index.html
    • style.css
    • ads.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 à 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. 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, 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.

2. Créer un lecteur vidéo simple

Commencez par modifier index.html pour créer un élément vidéo HTML5 simple, contenu dans un élément de mise en page, et un bouton pour déclencher la lecture. L'exemple suivant importe le SDK IMA et configure l'élément de conteneur AdDisplayContainer. Pour en savoir plus, consultez les étapes Importer le SDK IMA et Créer le conteneur d'annonces . 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

index.html
 
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
style.css
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});
ads.js

Ajoutez les balises nécessaires pour charger les fichiers style.css et ads.js. Modifiez ensuite styles.css pour rendre le lecteur vidéo responsif sur les appareils mobiles. Enfin, dans ads.js, déclarez vos variables et déclenchez la lecture de la vidéo lorsque vous cliquez sur le bouton de lecture.

Notez que l'extrait de code ads.js contient un appel à setUpIMA(), qui est défini dans la section Initialiser AdsLoader et effectuer une requête d'annonces .

3. Importer le SDK IMA

Ajoutez ensuite le framework IMA à l'aide d'une balise de script dans index.html, avant la balise pour ads.js. 

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
index.html

4. Créer le conteneur d'annonces

Dans la plupart des navigateurs, le SDK IMA utilise un élément de conteneur d'annonces dédié pour afficher à la fois des annonces et des éléments d'interface utilisateur liés aux annonces. La taille de ce conteneur doit être adaptée pour recouvrir l'élément vidéo à partir de l'angle supérieur gauche. La hauteur et la largeur des annonces placées dans ce conteneur sont définies par l'objet adsManager. Vous n'avez donc pas besoin de définir ces valeurs manuellement.

Pour implémenter cet élément de conteneur d'annonces, commencez par créer un div dans l'élément video-container. Modifiez ensuite le CSS pour positionner l'élément en haut à gauche de video-element. Enfin, ajoutez la fonction createAdDisplayContainer() pour créer l'objet AdDisplayContainer à l'aide du nouveau conteneur d'annonces div. 

<div id="adContainer"></div>
index.html
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
style.css
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}
ads.js

5. Initialiser AdsLoader et envoyer une demande d'annonces

Pour demander des annonces, créez une instance AdsLoader. Le constructeur AdsLoader utilise un objet AdDisplayContainer comme entrée et peut être utilisé pour traiter les objets AdsRequest associés à une URL de balise publicitaire spécifiée. Le tag d'annonce utilisé dans cet exemple contient une annonce pré-roll de 10 secondes. Vous pouvez tester cette URL de tag d'emplacement publicitaire ou toute autre URL à l'aide de l'outil IMA Video Suite Inspector.

Il est recommandé de ne conserver qu'une seule instance de AdsLoader pour l'ensemble du cycle de vie d'une page. Pour envoyer des requêtes d'annonces supplémentaires, créez un objet AdsRequest, mais réutilisez le même AdsLoader. Pour en savoir plus, consultez les questions fréquentes sur le SDK IMA.

Écoutez et répondez aux événements d'erreur et de chargement des annonces à l'aide de AdsLoader.addEventListener. Écoutez les événements suivants:

  • ADS_MANAGER_LOADED
  • AD_ERROR

Pour créer les écouteurs onAdsManagerLoaded() et onAdError(), consultez l'exemple suivant: 

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
      'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
      'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&' +
      'output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}
ads.js

6. Répondre aux événements AdsLoader

Lorsque AdsLoader charge des annonces, il émet un événement ADS_MANAGER_LOADED. Analysez l'événement transmis au rappel pour initialiser l'objet AdsManager. AdsManager charge les annonces individuelles telles que définies par la réponse à l'URL du tag d'emplacement publicitaire.

Assurez-vous de gérer les erreurs qui se produisent pendant le processus de chargement. Si les annonces ne se chargent pas, assurez-vous que la lecture multimédia se poursuit sans annonces pour ne pas perturber la lecture du contenu par l'utilisateur. 

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  adsManager.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
  adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}
ads.js

Pour en savoir plus sur les écouteurs définis dans la fonction onAdsManagerLoaded(), consultez les sous-sections suivantes:

Gérer les erreurs AdsManager

Le gestionnaire d'erreurs créé pour AdsLoader peut également servir de gestionnaire d'erreurs pour AdsManager. Consultez le gestionnaire d'événements qui réutilise la fonction onAdError(). 

adsManager.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);
ads.js

Gérer les événements de lecture et de pause

Lorsque AdsManager est prêt à insérer une annonce à afficher, il déclenche l'événement CONTENT_PAUSE_REQUESTED. Gérez cet événement en déclenchant une mise en pause sur le lecteur vidéo sous-jacent. De même, lorsqu'une annonce se termine, AdsManager déclenche l'événement CONTENT_RESUME_REQUESTED. Gérez cet événement en redémarrant la lecture de la vidéo de contenu sous-jacente. 

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);
ads.js

Pour connaître les définitions des fonctions onContentPauseRequested() et onContentResumeRequested(), consultez l'exemple suivant: 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}
ads.js

Gérer la lecture du contenu pendant les annonces non linéaires

AdsManager met en pause la vidéo du contenu lorsqu'une annonce est prête à être diffusée, mais ce comportement ne tient pas compte des annonces non linéaires, où le contenu continue de se lire pendant l'affichage de l'annonce. 

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
ads.js

Pour prendre en charge les annonces non linéaires, écoutez AdsManager pour émettre l'événement LOADED. Vérifiez si l'annonce est linéaire. Si ce n'est pas le cas, reprenez la lecture de l'élément vidéo.

Pour connaître la définition de la fonction onAdLoaded(), consultez l'exemple suivant. 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}
ads.js

7. Déclencher la mise en pause par clic sur les appareils mobiles

Étant donné que AdContainer se superpose à l'élément vidéo, les utilisateurs ne peuvent pas interagir directement avec le lecteur sous-jacent. Cela peut dérouter les utilisateurs sur les appareils mobiles, qui s'attendent à pouvoir appuyer sur un lecteur vidéo pour mettre la lecture en pause. Pour résoudre ce problème, le SDK IMA transmet tous les clics qui ne sont pas gérés par IMA depuis la superposition d'annonces à l'élément AdContainer, où ils peuvent être gérés. Cela ne s'applique pas aux annonces linéaires dans les navigateurs non mobiles, car cliquer sur l'annonce ouvre le lien de destination.

Pour implémenter la mise en pause par clic, ajoutez la fonction de gestionnaire de clics adContainerClick() appelée dans l'écouteur de chargement de la fenêtre. 

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}
ads.js

8. Démarrer AdsManager

Pour lancer la lecture de l'annonce, lancez et démarrez AdsManager. Pour prendre pleinement en charge les navigateurs mobiles, où vous ne pouvez pas lire automatiquement les annonces, déclenchez la lecture des annonces à partir des interactions des utilisateurs avec la page, par exemple en cliquant sur le bouton de lecture. 

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}
ads.js

9. Prise en charge du redimensionnement du lecteur

Pour que les annonces se redimensionnent dynamiquement et correspondent à la taille d'un lecteur vidéo, ou pour qu'elles correspondent aux modifications apportées à l'orientation de l'écran, appelez adsManager.resize() en réponse aux événements de redimensionnement de la fenêtre. 

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    let width = videoContent.clientWidth;
    let height = videoContent.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});
ads.js

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