Premiers pas

Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et applications. Les SDK IMA demander des annonces <ph type="x-smartling-placeholder"></ph> compatible avec la norme 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 du contenu vidéo, tandis que le SDK gère la lecture des annonces. Les annonces sont diffusées 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 le souhaitez, que vous souhaitez consulter ou suivre un exemple d'intégration terminé, téléchargez le exemple simple de GitHub. Si vous utilisez si vous êtes intéressé par un lecteur HTML5 avec le SDK pré-intégré, consultez la 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 principaux du SDK, illustré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 un chargeur d'annonces que vous pouvez réutiliser tout au long de 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'annonce, contrôle la lecture des annonces et écoute l'annonce déclenchés par le SDK.

Prérequis

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

  • Trois fichiers vides: <ph type="x-smartling-placeholder">
      </ph>
    • 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 besoin d'utiliser un serveur Web pour tester votre application. Le moyen le plus simple de démarrer un développement local est d'utiliser le serveur intégré de Python.

  1. À l'aide d'une ligne de commande, à partir du répertoire contenant exécutez 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

Modifiez d'abord le fichier index.html pour créer un élément vidéo HTML5 simple, contenu dans un élément et un bouton pour lancer la lecture. Ajoutez également les balises nécessaires pour charger le style.css et ads.js. Ensuite, modifiez styles.css pour que le lecteur vidéo réactifs pour les appareils mobiles. Enfin, dans ads.js, déclenchez la lecture de la vidéo .

index.html 
!<doctype html
>h<tml lang="en"<>/span>
  h<ead<>/span>
    t<itleI>MA HTML5 Simple Demo/<title
>    m<eta charset="utf-8"<>/span>
    m<eta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"<>/span>
    l<ink rel="stylesheet" href="style.css"<>/span>
  /<head
>  b<ody<>/span>
    d<iv id="page-content"<>/span>
      d<iv id="video-container"<>/span>
        v<ideo id="video-element"<>/span>
          s<ource src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4"<>/span>
          s<ource src="https://storage.googleapis.com/interactive-media-ads/media/android.webm"<>/span>
        /<video
>      /<div
>      b<utton id="play-button"P>lay/<button
>    /<div
>    s<cript 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 code de développement serveur), vous devriez pouvoir voir l'élément vidéo et la vidéo doit démarrer lorsque vous cliquez sur le bouton bouton de lecture.

3. Importer le SDK IMA

Ajoutez ensuite le framework IMA en utilisant un tag de script dans le fichier index.html, avant le tag du 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 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 l'événement 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, chargez des annonces (sauf si des annonces sont déjà chargées).
  • Lorsque la fenêtre du navigateur est redimensionnée, modifiez l'élément vidéo et adsManager des variables pour rendre la page responsive pour les appareils mobiles
<ph type="x-smartling-placeholder"> 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 à la fois les annonces et les éléments d'interface liés aux annonces. Ce conteneur doit être dimensionné de façon à pouvoir superposer l'élément vidéo du en haut à gauche. La hauteur et la largeur des annonces placées dans ce conteneur sont définies par le adsManager. Vous n'avez donc pas besoin de définir ces valeurs manuellement.

<ph type="x-smartling-placeholder">

Pour implémenter cet élément de conteneur d'annonces, créez d'abord un élément div dans le Élément video-container. Ensuite, mettez à jour le code CSS pour positionner l'élément en haut à gauche. dans l'angle de video-element. Enfin, définissez une variable pour le conteneur dans 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'annonces

Pour demander un ensemble d'annonces, créez une instance ima.AdsLoader. Cette instance accepte un objet AdDisplayContainer comme entrée et peut être utilisé pour traiter 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 à l'aide de la méthode IMA Video Suite Inspector.

Nous vous recommandons de ne conserver qu'une seule instance de ima.AdsLoader pour l'intégralité cycle de vie d'une page. Pour envoyer des demandes d'annonces supplémentaires, créez un 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, ima.AdsLoader émet une ADS_MANAGER_LOADED. Analysez l'événement transmis au rappel pour initialiser AdsManager. AdsManager charge les annonces individuelles selon la réponse à l'annonce. l'URL du tag.

En outre, veillez à traiter toutes les erreurs pouvant survenir pendant le processus de chargement. Si les annonces assurez-vous que la lecture des contenus multimédias se poursuit, sans publicité, afin de ne pas interférer avec de 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 l'AdsManager. Pour assurer une compatibilité totale avec les appareils mobiles dans les navigateurs, elle doit être déclenchée 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 s'assurer que les annonces sont redimensionnées dynamiquement pour s'adapter à la taille du lecteur vidéo, si l'écran modifie la taille ou l'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 sont utilisés pour suivre les changements d'état, déclencher la lecture et l'interruption du contenu vidéo et 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 pour l'affichage, il déclenche la CONTENT_PAUSE_REQUESTED. Gérez cet événement en déclenchant une pause sur la du lecteur vidéo sous-jacent. De même, lorsqu'une annonce se termine, AdsManager déclenche la CONTENT_RESUME_REQUESTED. Gérez cet événement en relançant la lecture sur le une 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é Cliquer pour mettre en pause 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 perturber les utilisateurs d'appareils mobiles, qui s'attendent à pouvoir appuyer sur un pour mettre en pause la lecture. Pour résoudre ce problème, le SDK IMA transmet les clics qui ne sont pas gérés par l'IMA de la superposition d'annonce vers l'élément AdContainer, où ils peuvent être gérés. Cela ne s'applique pas aux annonces linéaires diffusées sur d'autres navigateurs que les mobiles, car en cliquant sur l'annonce, .

Pour implémenter la fonctionnalité "Cliquer pour mettre en pause", ajoutez un gestionnaire de clics à AdContainer et déclenchez la lecture. ou mettre en pause des événements 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 sur des annonces non linéaires

AdsManager met la vidéo en pause lorsqu'une annonce est prête à être diffusée, ne tient pas compte des annonces non linéaires, dans lesquelles la lecture du contenu doit se poursuivre s'affiche. Pour accepter les annonces non linéaires, écoutez AdsManager pour émettre la LOADED. Vérifiez ensuite si l'annonce est linéaire. Si ce n'est pas le cas, reprenez la lecture .

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 à présent des annonces avec le SDK IMA. Pour en savoir plus les fonctionnalités avancées du SDK, consultez les autres guides exemples sur GitHub.