Commencer

Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et vos applications. Les SDK IMA peuvent demander des annonces à partir de n'importe quel ad server compatible VAST et gérer la lecture des annonces dans vos applications. Avec les SDK IMA côté client, vous contrôlez la lecture des contenus vidéo, tandis que le SDK gère la lecture des annonces. Les annonces sont diffusées dans un lecteur vidéo distinct positionné au-dessus du lecteur de contenu de l'application.

Ce guide explique comment intégrer le SDK IMA à une application de lecture vidéo simple. Si vous souhaitez afficher ou suivre un exemple d'intégration terminé, téléchargez l'exemple simple depuis GitHub. Si vous êtes intéressé par un lecteur HTML5 avec SDK intégré, consultez le plug-in SDK IMA pour Video.js.

Présentation du client IMA

La mise en œuvre d'IMA côté client implique quatre composants principaux du SDK, comme indiqué dans ce guide:

  • AdDisplayContainer : objet de conteneur dans lequel les annonces sont affichées.
  • AdsLoader : objet qui demande des annonces et gère les événements à partir de 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.

Conditions préalables

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, dans le répertoire contenant l'exécution de votre fichier index.html, procédez comme suit :
      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

Modifiez d'abord le fichier 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. Ajoutez également les balises nécessaires pour charger les fichiers style.css et ads.js. Modifiez ensuite le fichier styles.css pour que le lecteur vidéo soit adapté aux 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 le fichier index.html dans votre navigateur (via votre serveur de développement), l'élément vidéo doit s'afficher. La vidéo doit démarrer lorsque vous cliquez sur le bouton de lecture.

3. Importer le SDK IMA

Ensuite, ajoutez le framework IMA à l'aide d'un tag de script dans le fichier index.html, avant le tag 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 pages et de lecteurs 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 le chargement de la page terminé, initialisez le SDK IMA.
  • Lorsque vous cliquez sur le bouton de lecture de la vidéo, chargez les annonces (sauf si des annonces sont déjà chargées).
  • Lorsque la fenêtre du navigateur est redimensionnée, mettez à jour les dimensions de l'élément vidéo et de adsManager pour que la page s'affiche correctement 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'annonce dédié pour afficher les annonces et les éléments d'interface utilisateur associés. Ce conteneur doit être dimensionné pour superposer l'élément vidéo depuis 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 les définir manuellement.

Pour implémenter cet élément de conteneur d'annonce, commencez par créer une div dans l'élément video-container. Ensuite, mettez à jour 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 effectuer une demande d'annonce

Pour demander un ensemble d'annonces, créez une instance ima.AdsLoader. Cette instance utilise un objet AdDisplayContainer en entrée et peut servir à traiter des objets ima.AdsRequest associés à une URL de tag d'emplacement publicitaire spécifiée. Le tag d'emplacement publicitaire utilisé dans cet exemple contient une annonce vidéo pré-roll de 10 secondes. Vous pouvez tester cette URL ou celle d'un tag d'emplacement publicitaire à l'aide de l'outil IMA Video Suite Inspector.

Il est recommandé de ne conserver qu'une seule instance de ima.AdsLoader pendant le cycle de vie complet d'une page. Pour envoyer des demandes 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

Une fois les annonces chargées, l'événement 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 à traiter les erreurs susceptibles de se produire pendant le processus de chargement. Si les annonces ne se chargent pas, assurez-vous que la lecture du contenu multimédia se poursuit sans annonce afin d'éviter toute interférence avec l'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 l'AdsManager. Pour assurer une compatibilité totale avec les navigateurs mobiles, ce comportement doit être déclenché par une interaction de l'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 que les annonces soient redimensionnées de manière dynamique à la taille du lecteur vidéo, l'événement de redimensionnement de la fenêtre doit appeler adsManager.resize() si l'écran change de taille ou d'orientation.

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 d'interrompre la lecture du contenu vidéo, et d'enregistrer les erreurs.

Traiter les erreurs

Le gestionnaire d'erreurs créé pour AdsLoader peut servir de gestionnaire d'erreurs pour AdsManager en ajoutant un gestionnaire d'événements ayant 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 pause

Lorsque l'élément AdsManager est prêt à insérer une annonce à diffuser, il déclenche l'événement CONTENT_PAUSE_REQUESTED. Gérez cet événement en déclenchant une pause dans le lecteur vidéo sous-jacent. De même, lorsqu'une annonce se termine, AdsManager déclenche l'événement CONTENT_RESUME_REQUESTED. Pour gérer cet événement, redémarrez 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 fonctionnalité de mise en veille par un clic sur les appareils mobiles

Étant donné que AdContainer superpose l'élément vidéo, les utilisateurs ne peuvent pas interagir directement avec le lecteur sous-jacent. Cela peut perturber les utilisateurs d'appareils mobiles, qui s'attendent à pouvoir appuyer sur un lecteur vidéo pour interrompre la lecture. 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'annonce à l'élément AdContainer, où ils peuvent être gérés. Cette règle ne s'applique pas aux annonces linéaires diffusées dans des navigateurs non mobiles, car le fait de cliquer sur l'annonce ouvre le lien de clic.

Pour implémenter un clic de pause, ajoutez un gestionnaire de clics à 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 des annonces non linéaires

AdsManager met en pause la vidéo de contenu lorsqu'une annonce est prête à être diffusée, mais ce comportement ne tient pas compte des annonces non linéaires, pour lesquelles la lecture du contenu doit se poursuivre lorsque l'annonce est diffusée. Pour accepter 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, poursuivez 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 diffusez maintenant des annonces avec le SDK IMA. Pour découvrir d'autres fonctionnalités avancées du SDK, consultez les autres guides ou les exemples sur GitHub.