Inizia

Gli SDK IMA semplificano l'integrazione di annunci multimediali nei siti web e nelle app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server compatibile con VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK lato client IMA puoi mantenere il controllo della riproduzione dei video dei contenuti, mentre l'SDK gestisce la riproduzione degli annunci. Gli annunci vengono riprodotti in un video player separato posizionato sopra il video player dei contenuti dell'app.

Questa guida illustra come integrare l'SDK IMA in una semplice app video player. Se vuoi visualizzare o seguire un'integrazione di esempio completata, scarica questo semplice esempio da GitHub. Se ti interessa un player HTML5 con l'SDK preintegrato, prova il plug-in SDK IMA per Video.js.

Panoramica lato client IMA

L'implementazione lato client IMA prevede l'utilizzo di quattro componenti principali dell'SDK, illustrati in questa guida:

  • AdDisplayContainer: un oggetto contenitore in cui viene eseguito il rendering degli annunci.
  • AdsLoader: un oggetto che richiede annunci e gestisce gli eventi dalle risposte alle richieste di annunci. Devi ottimizzare un solo caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.
  • AdsRequest: un oggetto che definisce una richiesta di annunci. Le richieste di annunci specificano l'URL del tag annuncio VAST e parametri aggiuntivi, come le dimensioni dell'annuncio.
  • AdsManager: un oggetto che contiene la risposta alla richiesta di annunci, controlla la riproduzione dell'annuncio e ascolta gli eventi annunci attivati dall'SDK.

Prerequisiti

Prima di iniziare, avrai bisogno di:

  • Tre file vuoti:
    • index.html
    • style.css
    • ads.js
  • Python installato sul computer o un server web da utilizzare per i test

1. Avvia un server di sviluppo

Poiché l'SDK IMA carica le dipendenze tramite lo stesso protocollo della pagina da cui vengono caricate, devi utilizzare un server web per testare l'app. Il modo più semplice per avviare un server di sviluppo locale è utilizzare il server incorporato di Python.

  1. Utilizzando una riga di comando, dalla directory che contiene l'esecuzione del file index.html:
      python -m http.server 8000
    
  2. In un browser web, vai all'indirizzo http://localhost:8000/.

Puoi anche utilizzare qualsiasi altro server web, ad esempio Apache HTTP Server.

2. Creare un video player semplice

Innanzitutto, modifica index.html per creare un semplice elemento video HTML5, contenuto in un elemento wrapping, e un pulsante per attivare la riproduzione. Aggiungi anche i tag necessari per caricare i file style.css e ads.js. Poi, modifica styles.css per rendere il video player reattivo per i dispositivi mobili. Infine, in ads.js, attiva la riproduzione del video quando si fa clic sul pulsante di riproduzione.

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

Dopo aver completato questo passaggio, quando apri index.html nel browser (tramite il tuo server di sviluppo), dovresti riuscire a vedere l'elemento video e il video dovrebbe iniziare quando fai clic sul pulsante di riproduzione.

3. Importare l'SDK IMA

Poi, aggiungi il framework IMA utilizzando un tag script in index.html, prima del tag per 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. Allega gestori della pagina e del video player

Per modificare il comportamento del video player con JavaScript, aggiungi gestori di eventi che attivano le seguenti azioni:

  • Al termine del caricamento della pagina, inizializza l'SDK IMA.
  • Quando l'utente fa clic sul pulsante di riproduzione del video, carica gli annunci (a meno che non siano già stati caricati).
  • Quando la finestra del browser viene ridimensionata, aggiorna l'elemento video e le dimensioni adsManager per rendere la pagina adattabile ai dispositivi mobili
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. Creare il contenitore dell'annuncio

Nella maggior parte dei browser, l'SDK IMA utilizza un elemento contenitore annunci dedicato per visualizzare sia gli annunci sia gli elementi dell'interfaccia utente correlati agli annunci. Il contenitore deve essere ridimensionato in modo da sovrapporre l'elemento video dall'angolo superiore sinistro. L'altezza e la larghezza degli annunci posizionati in questo contenitore sono impostate dall'oggetto adsManager, quindi non è necessario impostare questi valori manualmente.

Per implementare questo elemento contenitore annunci, devi prima creare un nuovo div all'interno dell'elemento video-container. Successivamente, aggiorna il CSS in modo da posizionare l'elemento nell'angolo in alto a sinistra di video-element. Infine, definisci una variabile per il contenitore all'interno della funzione initializeIMA() che viene eseguita quando la pagina viene caricata.

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. Inizializzare AdsLoader e inviare una richiesta di annunci

Per richiedere un insieme di annunci, crea un'istanza ima.AdsLoader. Questa istanza prende un oggetto AdDisplayContainer come input e può essere utilizzata per elaborare ima.AdsRequest oggetti associati a un URL di tag annuncio specificato. Il tag annuncio utilizzato in questo esempio contiene un annuncio pre-roll di 10 secondi. Puoi verificare questo o qualsiasi URL di tag annuncio utilizzando IMA Video Suite Inspector.

Come best practice, gestisci una sola istanza di ima.AdsLoader per l'intero ciclo di vita di una pagina. Per effettuare richieste di annunci aggiuntive, crea un nuovo oggetto ima.AdsRequest, ma riutilizza lo stesso ima.AdsLoader. Per ulteriori informazioni, leggi le domande frequenti sull'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. Ascolta gli eventi AdsLoader

Una volta caricati correttamente gli annunci, ima.AdsLoader emette un evento ADS_MANAGER_LOADED. Analizza l'evento passato al callback per inizializzare l'oggetto AdsManager. AdsManager carica i singoli annunci come definito dalla risposta all'URL del tag annuncio.

Inoltre, assicurati di gestire eventuali errori che potrebbero verificarsi durante il processo di caricamento. Se gli annunci non vengono caricati, assicurati che la riproduzione dei contenuti multimediali continui, senza annunci, in modo da non interferire con l'esperienza dell'utente.

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. Avvia AdsManager

Per avviare la riproduzione dell'annuncio, devi avviare AdsManager. Per supportare completamente i browser mobile, questa operazione deve essere attivata da un'interazione dell'utente.

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. Rendere AdsManager reattivo

Per fare in modo che gli annunci vengano ridimensionati in modo dinamico per corrispondere alle dimensioni del video player, se lo schermo cambia dimensioni o orientamento, l'evento di ridimensionamento della finestra deve chiamare 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. Ascolta gli eventi di AdsManager

AdsManager attiva anche diversi eventi che devono essere gestiti. Questi eventi vengono utilizzati per monitorare le modifiche di stato, attivare la riproduzione e la pausa dei contenuti video e registrare gli errori.

Gestione degli errori

Il gestore degli errori creato per AdsLoader può fungere da gestore degli errori per AdsManager aggiungendo un nuovo gestore di eventi con la stessa funzione di callback.

ads.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

Attivazione degli eventi di riproduzione e pausa

Quando AdsManager è pronto per inserire un annuncio per la visualizzazione, attiva l'evento CONTENT_PAUSE_REQUESTED. Per gestire questo evento, attiva una pausa sul video player sottostante. Allo stesso modo, quando un annuncio viene completato, AdsManager attiva l'evento CONTENT_RESUME_REQUESTED. Per gestire questo evento, riavvia la riproduzione sul video dei contenuti sottostante.

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

Attivare la funzionalità click-to-pause sui dispositivi mobili

Poiché AdContainer si sovrappone all'elemento video, gli utenti non possono interagire direttamente con il player sottostante. Questo può confondere gli utenti di dispositivi mobili, che si aspettano di poter toccare un video player per mettere in pausa la riproduzione. Per risolvere questo problema, l'SDK IMA trasmette all'elemento AdContainer tutti i clic non gestiti da IMA dall'overlay dell'annuncio, dove possono essere gestiti. Questo non vale per gli annunci lineari sui browser non per dispositivi mobili, perché facendo clic sull'annuncio si apre il link di clickthrough.

Per implementare la funzione click-to-pause, aggiungi un gestore di clic a AdContainer e attiva gli eventi di riproduzione o pausa sul video sottostante.

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

...

Attivare la riproduzione negli annunci non lineari

AdsManager mette in pausa il video di contenuti quando l'annuncio è pronto per la riproduzione, ma questo comportamento non prende in considerazione gli annunci non lineari in cui la riproduzione dei contenuti deve continuare mentre l'annuncio viene visualizzato. Per supportare gli annunci non lineari, esamina l'evento AdsManager per emettere l'evento LOADED. Poi, controlla se l'annuncio è lineare e, in caso contrario, riprendi la riproduzione dell'elemento video.

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

È tutto. Ora richiedi e visualizzi gli annunci con l'SDK IMA. Per scoprire di più sulle funzionalità avanzate dell'SDK, consulta le altre guide o gli esempi su GitHub.