Premiers pas

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 é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 via le 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. Ajoutez également 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éclenchez la lecture de la vidéo lorsque l'utilisateur clique sur le bouton de lecture.

index.html 
<!doctype html>
<html lang="en">
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="page-content">
      <div id="video-container">
        <video id="video-element">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="ads.js"></script>
  </body>
</html>
 style.css 
#page-content {
  position: relative;
  /* this element's width controls the effective height */
  /* of the video container's padding-bottom */
  max-width: 640px;
  margin: 10px auto;
}

#video-container {
  position: relative;
  /* forces the container to match a 16x9 aspect ratio */
  /* replace with 75% for a 4:3 aspect ratio, if needed */
  padding-bottom: 56.25%;
}

#video-element {
  /* forces the contents to fill the container */
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
 ads.js 
var videoElement;

// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

Une fois cette étape terminée, lorsque vous ouvrez index.html dans votre navigateur (via votre serveur de développement), vous devriez pouvoir voir l'élément vidéo et la vidéo devrait commencer lorsque vous cliquez sur le bouton de lecture.

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.

index.html 
...

        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

4. Associer des gestionnaires de page et de lecteur vidéo

Pour modifier le comportement du lecteur vidéo avec JavaScript, ajoutez des gestionnaires d'événements qui déclenchent les actions suivantes:

  • Une fois la page chargée, initialisez le SDK IMA.
  • Lorsque l'utilisateur clique sur le bouton de lecture de la vidéo, les annonces sont chargées (sauf si des annonces sont déjà chargées).
  • Lorsque la fenêtre du navigateur est redimensionnée, mettez à jour l'élément vidéo et les dimensions adsManager pour rendre la page responsive sur les appareils mobiles.
ads.js 
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;

window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  initializeIMA();
  videoElement.addEventListener('play', function(event) {
    loadAds(event);
  });
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

window.addEventListener('resize', function(event) {
  console.log("window resized");
});

function initializeIMA() {
  console.log("initializing IMA");
}

function loadAds(event) {
  // Prevent this function from running on if there are already ads loaded
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // Prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");
}

5. 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. Ensuite, modifiez le CSS pour positionner l'élément en haut à gauche de video-element. Enfin, définissez une variable pour le conteneur dans la fonction initializeIMA() qui s'exécute lors du chargement de la page.

index.html 
...

  <div id="video-container">
    <video id="video-element" controls>
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
    </video>
    <div id="ad-container"></div>
  </div>

...
 style.css 
...

#ad-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
 ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
}

6. Initialiser AdsLoader et envoyer une demande d'annonces

Pour demander un ensemble d'annonces, créez une instance ima.AdsLoader. Cette instance reçoit un objet AdDisplayContainer en entrée et peut être utilisée pour traiter les objets ima.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 ima.AdsLoader pour l'ensemble du cycle de vie d'une page. Pour envoyer des requêtes d'annonces supplémentaires, créez un objet ima.AdsRequest, mais réutilisez le même ima.AdsLoader. Pour en savoir plus, consultez les questions fréquentes sur le SDK IMA.

ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

  // Let the AdsLoader know when the video has ended
  videoElement.addEventListener('ended', function() {
    adsLoader.contentComplete();
  });

  var 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 = videoElement.clientWidth;
  adsRequest.linearAdSlotHeight = videoElement.clientHeight;
  adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
  adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;

  // Pass the request to the adsLoader to request ads
  adsLoader.requestAds(adsRequest);
}

7. Écouter les événements AdsLoader

Lorsque les annonces sont chargées, ima.AdsLoader é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.

Veillez également à gérer les erreurs susceptibles de se produire lors du processus de chargement. Si les annonces ne se chargent pas, assurez-vous que la lecture multimédia continue, sans annonces, afin de ne pas perturber l'expérience utilisateur.

ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded,
      false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError,
      false);

...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Instantiate the AdsManager from the adsLoader response and pass it the video element
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);
}

function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  if(adsManager) {
    adsManager.destroy();
  }
}

8. Démarrer AdsManager

Pour lancer la lecture de l'annonce, vous devez démarrer AdsManager. Pour une compatibilité totale avec les navigateurs mobiles, cette action doit être déclenchée par une interaction utilisateur.

ads.js 
...

function loadAds(event) {
  // prevent this function from running on every play event
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");

  // Initialize the container. Must be done via a user action on mobile devices.
  videoElement.load();
  adDisplayContainer.initialize();

  var width = videoElement.clientWidth;
  var height = videoElement.clientHeight;
  try {
    adsManager.init(width, height, google.ima.ViewMode.NORMAL);
    adsManager.start();
  } catch (adError) {
    // Play the video without ads, if an error occurs
    console.log("AdsManager could not be started");
    videoElement.play();
  }
}

...

9. Rendre AdsManager responsif

Pour vous assurer que les annonces sont redimensionnées de manière dynamique pour s'adapter à la taille du lecteur vidéo, si l'écran change de taille ou d'orientation, l'événement de redimensionnement de la fenêtre doit appeler adsManager.resize().

ads.js 
...

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

...

10. Écouter les événements AdsManager

AdsManager déclenche également plusieurs événements qui doivent être gérés. Ces événements permettent de suivre les changements d'état, de déclencher la lecture et la mise en pause de la vidéo du contenu, et d'enregistrer les erreurs.

Traiter les erreurs

Le gestionnaire d'erreur créé pour le AdsLoader peut servir de gestionnaire d'erreur pour le AdsManager en ajoutant un nouveau gestionnaire d'événements avec la même fonction de rappel.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

Déclencher des événements de lecture et de mise en 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.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

function onContentPauseRequested() {
  videoElement.pause();
}

function onContentResumeRequested() {
  videoElement.play();
}

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 le calque d'annonce à 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 par clic, ajoutez un gestionnaire de clic à AdContainer et déclenchez des événements de lecture ou de mise en pause sur la vidéo sous-jacente.

ads.js 
...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adContainer.addEventListener('click', adContainerClick);
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

...

function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoElement.paused) {
    videoElement.play();
  } else {
    videoElement.pause();
  }
}

...

Déclencher la lecture sur 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 doit continuer à être lu pendant l'affichage de l'annonce. Pour prendre en charge les annonces non linéaires, écoutez AdsManager pour émettre l'événement LOADED. Vérifiez ensuite si l'annonce est linéaire. Si ce n'est pas le cas, reprenez la lecture de l'élément vidéo.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

function onAdLoaded(adEvent) {
  var ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoElement.play();
  }
}

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.