Configurer le SDK IMA

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

Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et applications. Ils peuvent demander des annonces à n'importe quel ad server compatible avec VAST et gérer leur lecture dans vos applications. Avec les SDK IMA côté client, vous gardez le contrôle de la lecture des vidéos de contenu, tandis que le SDK gère la lecture des annonces. Les annonces sont diffusées dans un lecteur vidéo distinct, placé 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 consulter ou suivre un exemple d'intégration complet, téléchargez l' exemple simple depuis GitHub. Si vous recherchez un lecteur HTML5 avec le SDK préintégré, consultez le plug-in du SDK IMA pour Video.js.

Présentation d'IMA côté client

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

  • AdDisplayContainer : Objet conteneur qui spécifie l'endroit où IMA affiche les éléments d'interface utilisateur des annonces et mesure la visibilité, y compris Active View et Open Measurement.
  • AdsLoader: Objet qui demande des annonces et gère les événements des réponses aux demandes 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 demande d'annonce. Les demandes 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 qui contient la réponse à la demande d'annonce, contrôle la lecture de l'annonce et écoute les événements d'annonce 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 d'encapsulation , et un bouton pour déclencher la lecture. L'exemple suivant importe le SDK IMA et configure l'élément conteneur AdDisplayContainer. Pour en savoir plus, consultez les étapes Importer le SDK IMA et Créer le conteneur d'annonces , respectivement. 

<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>

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

Ajoutez les tags nécessaires pour charger les fichiers style.css et ads.js. Modifiez ensuite styles.css pour que le lecteur vidéo soit adapté aux appareils mobiles. Enfin, dans ads.js, déclarez vos variables et déclenchez la lecture 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 demande d'annonce .

3. Importer le SDK IMA

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

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

4. Créer le conteneur d'annonces

Dans la plupart des navigateurs, le SDK IMA utilise un élément conteneur d'annonces dédié pour afficher à la fois les annonces et les éléments d'interface utilisateur associés aux annonces. La taille de ce conteneur doit être définie de manière à ce qu'il recouvre l'élément vidéo à partir du coin 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 conteneur d'annonces, commencez par créer un nouveau div dans l'élément video-container. Mettez ensuite à jour le code CSS pour positionner l'élément dans le coin supérieur gauche du video-element. Enfin, ajoutez la createAdDisplayContainer() fonction pour créer l' AdDisplayContainer objet à l'aide du nouveau conteneur d'annonces div. 

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

5. Initialiser AdsLoader et effectuer une demande d'annonce

Pour demander des annonces, créez une AdsLoader instance. Le constructeur AdsLoader prend un AdDisplayContainer objet comme entrée et peut être utilisé pour traiter AdsRequest objets associés à une URL de tag d'emplacement publicitaire spécifiée. Le tag d'emplacement publicitaire 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.

Nous vous recommandons de ne conserver qu'une seule instance de AdsLoader pendant toute la durée de vie d'une page. Pour effectuer des demandes d'annonces supplémentaires, créez un nouvel objet AdsRequest, mais réutilisez le même AdsLoader. Pour en savoir plus, consultez les questions fréquentes sur le SDK IMA.

Écoutez les annonces chargées et les événements d'erreur, et répondez-y à 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);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);

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

6. Répondre aux événements AdsLoader

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

Assurez-vous de gérer toutes les erreurs qui se produisent lors du processus de chargement. Si les annonces ne se chargent pas, assurez-vous que la lecture du contenu multimédia se poursuit sans annonces pour éviter d'interférer avec la visualisation 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();
}

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 le AdsLoader peut également servir de gestionnaire d'erreurs pour le AdsManager. Consultez le gestionnaire d'événements qui réutilise la fonction onAdError(). 

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

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

Lorsque le AdsManager est prêt à insérer une annonce à afficher, il déclenche l' CONTENT_PAUSE_REQUESTED événement. Gérez cet événement en déclenchant une pause sur le lecteur vidéo sous-jacent. De même, lorsqu'une annonce est terminée, le AdsManager déclenche l' CONTENT_RESUME_REQUESTED événement. Gérez cet événement en redémarrant la lecture sur 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);

Pour obtenir 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();
}

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

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

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

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

Pour obtenir 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();
  }
}

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

Étant donné que le AdContainer recouvre 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 de la superposition d'annonces à l'élément AdContainer, où ils peuvent être gérés. Cela ne s'applique pas aux annonces linéaires sur les navigateurs non mobiles, car cliquer sur l'annonce ouvre le lien de destination.

Pour implémenter la mise en pause au 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();
  }
}

8. Démarrer AdsManager

Pour démarrer la lecture des annonces, lancez et démarrez AdsManager. Pour une compatibilité totale avec 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();
  }
}

9. Prendre en charge le redimensionnement du lecteur

Pour que les annonces soient redimensionnées de manière dynamique et correspondent à la taille d'un lecteur vidéo, ou pour qu'elles s'adaptent aux changements d'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);
  }
});

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