Premiers pas

Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et applications. Les SDK IMA peuvent demander des annonces à n'importe quel ad server compatible avec VAST et gérer la lecture des annonces dans vos applications. Avec les SDK IMA côté client, vous gardez le contrôle de 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 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 afficher ou suivre un exemple d'intégration terminé, téléchargez l'exemple simple sur GitHub. Si vous êtes intéressé par un lecteur HTML5 dans lequel le SDK est pré-intégré, découvrez le plug-in 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, présentés dans ce guide:

  • AdDisplayContainer : objet conteneur dans lequel les annonces sont affichées.
  • AdsLoader : objet qui demande des annonces et gère les événements provenant des réponses aux demandes d'annonces. Vous ne devez instancier qu'un seul chargeur d'annonces, que vous pourrez réutiliser pendant toute la durée de vie de l'application.
  • AdsRequest : objet qui définit une demande d'annonces. 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'annonces, contrôle la lecture des annonces 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 elle est chargée, vous devez utiliser un serveur Web pour tester votre application. Le moyen le plus simple de démarrer un serveur de développement local est d'utiliser le serveur intégré à Python.

  1. À l'aide d'une ligne de commande, dans le répertoire contenant votre fichier index.html, exécutez :
      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, par exemple Apache HTTP Server.

2. Créer un lecteur vidéo simple

Commencez par modifier le fichier index.html pour créer un élément vidéo HTML5 simple, contenu dans un élément d'encapsulation, ainsi qu'un bouton permettant de déclencher la lecture. Ajoutez également les balises nécessaires au chargement des fichiers style.css et ads.js. Modifiez ensuite le fichier styles.css pour rendre le lecteur vidéo responsif pour 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 le fichier index.html dans votre navigateur (via votre serveur de développement), vous devriez voir l'élément vidéo et la vidéo devrait 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 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 lecteur 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 le chargement de la page terminé, initialisez le SDK IMA.
  • Lorsque l'utilisateur clique sur le bouton de lecture de la vidéo, les annonces sont chargées (sauf si elles sont déjà chargées).
  • Lorsque la fenêtre du navigateur est redimensionnée, modifiez les dimensions de l'élément vidéo et de adsManager pour que la page soit 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 les annonces et les éléments d'interface utilisateur associés aux annonces. Ce conteneur doit être dimensionné de manière à superposer 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 élément 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 envoyer une demande d'annonces

Pour demander un ensemble d'annonces, créez une instance ima.AdsLoader. Cette instance utilise un objet AdDisplayContainer en entrée et peut être utilisée pour traiter les 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 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 gérer qu'une seule instance de ima.AdsLoader pendant tout le cycle de vie 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

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

En outre, veillez à gérer les erreurs qui peuvent 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 annonces, afin de ne pas interférer avec 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 lancer le AdsManager. Pour une compatibilité complète avec les navigateurs mobiles, il 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 façon dynamique en fonction de 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 pause 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 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 du contenu vidéo sous-jacent.

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 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 mettre la lecture en pause. Pour résoudre ce problème, le SDK IMA transmet tous les clics non gérés par IMA depuis la superposition de l'annonce à l'élément AdContainer, où ils peuvent être gérés. Cela ne s'applique pas aux annonces linéaires diffusées dans des navigateurs non mobiles, car un clic sur l'annonce ouvre le lien de clic.

Pour implémenter la fonctionnalité de mise en pause par clic, 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éclenchement de la lecture des annonces non linéaires

L'élément AdsManager met en pause la vidéo du contenu lorsqu'une annonce est prête à être lue. Toutefois, ce comportement ne tient pas compte des annonces non linéaires, pour lesquelles la lecture du contenu doit se poursuivre pendant la diffusion de l'annonce. Pour accepter les annonces non linéaires, écoutez AdsManager pour émettre l'événement LOADED. Vérifiez ensuite si l'annonce est linéaire et, si ce n'est pas le cas, reprenez la lecture au niveau 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 des annonces à l'aide du SDK IMA. Pour en savoir plus sur les fonctionnalités avancées du SDK, consultez les autres guides ou les exemples sur GitHub.