Pour discuter de nos produits et nous faire part de vos commentaires, rejoignez le canal Discord officiel Ad Manager sur le serveur de la communauté Google Advertising and Measurement.

Cette page a été traduite par l'API Cloud Translation.

Configurer le SDK IMA

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 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, 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 afficher ou suivre un exemple d'intégration complet, téléchargez l'exemple simple depuis GitHub. Si vous êtes intéressé par un lecteur HTML5 avec le SDK préintégré, consultez 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, qui sont présentés dans ce guide :

AdDisplayContainer : Objet conteneur qui spécifie où IMA affiche les éléments d'UI 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'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 contenant la réponse à la demande d'annonces, contrôlant la lecture des annonces et écoutant 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 est d'utiliser le serveur intégré de Python.

À 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
```
Remarque : http.server n'est disponible que dans Python 3.x.
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 de conteneur AdDisplayContainer. Pour en savoir plus, consultez respectivement les étapes Importer le SDK IMA et Créer le conteneur d'annonces .

<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>
index.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;
}style.css

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();
});ads.js

Ajoutez les balises nécessaires pour charger les fichiers style.css et ads.js. Modifiez ensuite styles.css pour rendre le lecteur vidéo responsive sur les appareils mobiles. Enfin, dans ads.js, déclarez vos variables et déclenchez la lecture de la 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 Initialize the AdsLoader and make an ads request (Initialiser AdsLoader et envoyer une demande d'annonces).

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.

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

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. La taille de ce conteneur doit être définie de manière à ce qu'il recouvre 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, ajoutez la fonction createAdDisplayContainer() pour créer l'objet AdDisplayContainer à l'aide du nouveau conteneur d'annonces div.

<div id="adContainer"></div>index.html

#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}style.css

/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}ads.js

5. Initialiser AdsLoader et envoyer une demande d'annonce

Pour demander des annonces, créez une instance AdsLoader. Le constructeur AdsLoader accepte un objet AdDisplayContainer comme entrée et peut être utilisé pour traiter les objets AdsRequest associés à une URL de tag d'annonce 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 n'importe quelle autre) à l'aide de l'outil Video Suite Inspector IMA.

Il est recommandé de ne conserver qu'une seule instance de AdsLoader pour l'ensemble du cycle de vie d'une page. Pour effectuer des demandes d'annonces supplémentaires, créez un objet AdsRequest, mais réutilisez le même AdsLoader. Pour en savoir plus, consultez les questions fréquentes sur le SDK IMA.

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

  // 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);
}ads.js

6. Répondre aux événements AdsLoader

Lorsque AdsLoader charge correctement les annonces, il é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 qu'elles sont définies par la réponse à l'URL du tag d'emplacement publicitaire.

Veillez à gérer 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 ne pas gêner 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();
}ads.js

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

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

Gérer les événements de lecture et de 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 pause sur le lecteur vidéo sous-jacent. De même, lorsqu'une annonce est terminée, 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.

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);ads.js

Pour obtenir des 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();
}ads.js

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

La méthode 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, où le contenu continue d'être diffusé pendant l'affichage de l'annonce.

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

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

Pour 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();
  }
}ads.js

7. Déclencher le clic pour mettre en pause sur les appareils mobiles

Étant donné que 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 non gérés par IMA depuis 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 un clic sur l'annonce ouvre le lien de destination.

Pour implémenter la fonctionnalité "cliquer pour mettre en pause", 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();
  }
}ads.js

8. Démarrer AdsManager

Pour lancer la lecture de l'annonce, initiez et démarrez le 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, comme le fait de cliquer 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();
  }
}ads.js

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);
  }
});ads.js

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.