Inizia

Gli SDK IMA ti consentono di integrare facilmente gli annunci multimediali nei tuoi siti web e nelle tue 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, mantieni il controllo della riproduzione dei video di contenuti, mentre l'SDK gestisce la riproduzione degli annunci. Gli annunci vengono riprodotti in un video player separato posizionato sopra il video player di contenuti dell'app.

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

Panoramica lato client IMA

L'implementazione del lato client IMA comporta quattro componenti principali dell'SDK, illustrati in questa guida:

  • AdDisplayContainer: un oggetto container in cui vengono visualizzati gli annunci.
  • AdsLoader: un oggetto che richiede annunci e gestisce gli eventi dalle risposte alle richieste di annunci. È consigliabile istituire un solo caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.
  • AdsRequest: un oggetto che definisce una richiesta di annuncio. Le richieste di annunci specificano l'URL del tag annuncio VAST e altri parametri, come le dimensioni dell'annuncio.
  • AdsManager: un oggetto contenente la risposta alla richiesta di annuncio, controlla la riproduzione dell'annuncio e rimane in ascolto degli eventi dell'annuncio attivati dall'SDK.

Prerequisiti

Prima di iniziare ti serviranno:

  • Tre file vuoti:
    • indice.html
    • stile.css
    • ads.js
  • Python installato sul computer o su un server web da utilizzare per il test

1. Avvia un server di sviluppo

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

  1. Utilizzando una riga di comando, dalla directory contenente il tuo file index.html esegui: 
      python -m http.server 8000
  2. In un browser web, vai a http://localhost:8000/

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

2. Creare un video player semplice

Innanzitutto, modifica il file index.html in modo da 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. Successivamente, modifica styles.css per rendere il video player adattabile ai dispositivi mobili. Infine, in ads.js, attiva la riproduzione video quando viene fatto 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 tuo browser (tramite il tuo server di sviluppo) dovresti riuscire a vedere l'elemento video, che deve iniziare quando fai clic sul pulsante di riproduzione.

3. Importa l'SDK IMA

Poi, aggiungi il framework IMA utilizzando un tag script in index.html, prima del tag per ads.js.

indice.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. Collega gestori di pagina e video player

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

  • Al termine del caricamento della pagina, inizializza l'SDK IMA.
  • Quando viene fatto clic sul pulsante di riproduzione del video, carica gli annunci (a meno che non siano già stati caricati annunci).
  • 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 di annunci

Nella maggior parte dei browser, l'SDK IMA utilizza un elemento contenitore di annunci dedicato per visualizzare annunci ed elementi UI correlati agli annunci. Questo contenitore deve essere dimensionato per sovrapporre l'elemento video dall'angolo superiore sinistro. L'altezza e la larghezza degli annunci in questo contenitore sono impostate dall'oggetto adsManager, quindi non è necessario impostarli manualmente.

Per implementare questo elemento contenitore dell'annuncio, devi prima creare un nuovo elemento div all'interno dell'elemento video-container. Aggiorna quindi il CSS per posizionare l'elemento nell'angolo in alto a sinistra di video-element. Infine, definisci una variabile per il container 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. Inizializza il generatore di annunci e invia una richiesta di annuncio

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 gli oggetti ima.AdsRequest associati a un URL del tag annuncio specificato. Il tag annuncio utilizzato in questo esempio contiene un annuncio pre-roll di 10 secondi. Puoi testare questo o qualsiasi URL di tag annuncio utilizzando lo strumento IMA Video Suite Inspector.

Come best practice, mantieni una sola istanza di ima.AdsLoader per l'intero ciclo di vita di una pagina. Per effettuare altre richieste di annuncio, crea un nuovo oggetto ima.AdsRequest, ma riutilizza lo stesso ima.AdsLoader. Per ulteriori informazioni, consulta 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

Quando gli annunci vengono caricati correttamente, ima.AdsLoader emette un evento ADS_MANAGER_LOADED. Analizza l'evento trasmesso 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 la procedura 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 degli annunci, devi avviare AdsManager. Per supportare completamente i browser per dispositivi mobili, questo valore dovrebbe essere attivato 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. Rendi adattabile il gestore annunci

Per assicurarti che gli annunci vengano ridimensionati in modo dinamico per adattarsi alle dimensioni del video player, se l'orientamento o le dimensioni dello schermo cambiano, 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

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

Gestione degli errori

Il gestore di errori creato per AdsLoader può fungere da gestore di 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. Puoi gestire questo evento attivando una pausa sul video player sottostante. Analogamente, quando un annuncio viene completato, AdsManager attiva l'evento CONTENT_RESUME_REQUESTED. Per gestire questo evento, riavvia la riproduzione sul video sottostante dei contenuti.

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

Attivazione della funzione click-to-pause sui dispositivi mobili

Poiché AdContainer si sovrappone all'elemento video, gli utenti non possono interagire direttamente con il player sottostante. Ciò può confondere gli utenti sui 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 i clic non gestiti dall'IMA dall'overlay dell'annuncio all'elemento AdContainer, da cui può essere gestito. Questo non vale per gli annunci lineari su browser non mobile, in quanto il clic sull'annuncio apre il link di clickthrough.

Per implementare la funzionalità click-to-pause, aggiungi un gestore dei 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();
  }
}

...

Attivazione della riproduzione sugli annunci non lineari

AdsManager mette in pausa il video di contenuti quando un annuncio è pronto per la riproduzione, ma questo comportamento non tiene conto degli annunci non lineari, in cui i contenuti dovrebbero continuare a essere riprodotti mentre l'annuncio viene visualizzato. Per supportare gli annunci non lineari, ascolta AdsManager per emettere l'evento LOADED. Controlla se l'annuncio è lineare e, in caso negativo, riprendi la riproduzione sull'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, consultate le altre guide o gli esempi su GitHub.