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.
- À l'aide d'une ligne de commande, à partir du répertoire contenant
exécutez votre fichier index.html:
python -m http.server 8000
- 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> <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 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
... </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
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.
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.
... <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
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.jsvar 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.
... 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()
.
... 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.
... 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.
... 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.
... 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
.
... 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.