Per iniziare

Gli SDK IMA semplificano l'integrazione degli annunci multimediali nei tuoi siti web e nelle tue app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server conforme a VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK lato client IMA, mantieni 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 mostra come integrare l'SDK IMA in una semplice app di video player. Se vuoi visualizzare o seguire un'integrazione di esempio completata, scarica l'esempio semplice da GitHub. Se ti interessa un player HTML5 con l'SDK preintegrato, dai un'occhiata al plug-in SDK IMA per Video.js.

Panoramica della tecnologia IMA lato client

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

  • AdDisplayContainer: un oggetto contenitore che specifica dove IMA esegue il rendering degli elementi dell'interfaccia utente dell'annuncio e misura la visibilità, incluse Visualizzazione attiva e Open Measurement.
  • AdsLoader: un oggetto che richiede annunci e gestisce gli eventi delle risposte alle richieste di annunci. Devi solo inizializzare un 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, nonché parametri aggiuntivi, come le dimensioni dell'annuncio.
  • AdsManager: un oggetto che contiene la risposta alla richiesta di annunci, controlla la riproduzione degli annunci e ascolta gli eventi correlati agli annunci attivati dall'SDK.

Prerequisiti

Prima di iniziare, ti serviranno:

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

1. Avviare 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 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 index.html per creare un semplice elemento video HTML5, contenuto in un elemento di wrapping, e un pulsante per avviare 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 adattabile ai dispositivi mobili. Infine, in ads.js, attiva la riproduzione del 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 browser (tramite il server di sviluppo), dovresti riuscire a vedere l'elemento video, che dovrebbe avviarsi quando fai clic sul pulsante di riproduzione.

3. Importa l'SDK IMA

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 di pagine e video player

Per modificare il comportamento del video player con JavaScript, aggiungi gestori 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).
  • Quando la finestra del browser viene ridimensionata, aggiorna le dimensioni dell'elemento video e di 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. Crea il contenitore dell'annuncio

Nella maggior parte dei browser, l'SDK IMA utilizza un elemento contenitore degli annunci dedicato per la visualizzazione sia degli annunci sia degli elementi dell'interfaccia utente correlati agli annunci. Le dimensioni di questo contenitore devono essere impostate in modo da sovrapporre l'elemento video dall'angolo in alto a sinistra. L'altezza e la larghezza degli annunci posizionati in questo contenitore sono impostate dall'oggetto adsManager, pertanto non è necessario impostare questi valori manualmente.

Per implementare questo elemento contenitore dell'annuncio, crea innanzitutto un nuovo div all'interno dell'elemento video-container. Aggiorna il CSS per posizionare l'elemento nell'angolo in alto a sinistra del video-element. Infine, definisci una variabile per il contenitore all'interno della funzione initializeIMA() che viene eseguita al caricamento della pagina.

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 AdsLoader ed effettua una richiesta di annunci

Per richiedere un insieme di annunci, crea un'istanza ima.AdsLoader. Questa istanza accetta un oggetto AdDisplayContainer come input e può essere utilizzata per elaborare oggetti AdDisplayContainer associati a un URL del tag annuncio specificato.ima.AdsRequest Il tag annuncio utilizzato in questo esempio contiene un annuncio pre-roll di 10 secondi. Puoi testare questo o qualsiasi altro URL del tag annuncio utilizzando 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 ulteriori richieste di annunci, 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 passato al callback per inizializzare l'oggetto AdsManager. AdsManager carica i singoli annunci come definiti dalla risposta all'URL del tag annuncio.

Inoltre, assicurati di gestire gli eventuali errori che potrebbero verificarsi durante il processo di caricamento. Se gli annunci non si caricano, 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 il 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 adattabile

Per assicurarti che gli annunci vengano ridimensionati in modo dinamico in base alle dimensioni del video player, se lo schermo cambia dimensione 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 AdsManager

AdsManager attiva anche diversi eventi che devono essere gestiti. Questi eventi vengono utilizzati per monitorare le modifiche dello stato, attivare la riproduzione e la messa in pausa del video dei contenuti 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 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 di eventi di riproduzione e messa in pausa

Quando AdsManager è pronto a inserire un annuncio da visualizzare, attiva l'evento CONTENT_PAUSE_REQUESTED. Gestisci questo evento attivando una messa in pausa sul video player sottostante. Analogamente, quando un annuncio viene completato, AdsManager attiva l'evento CONTENT_RESUME_REQUESTED. Gestisci questo evento riavviando la riproduzione del video dei contenuti sottostanti.

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 funzionalità Interrompi con un clic sui dispositivi mobili

Poiché AdContainer sovrappone l'elemento video, gli utenti non possono interagire direttamente con il player sottostante. Ciò può confondere gli utenti che utilizzano dispositivi mobili, i quali si aspettano di poter toccare un visualizzatore video per mettere in pausa la riproduzione. Per risolvere il problema, l'SDK IMA passa gli eventuali clic non gestiti da IMA dall'overlay dell'annuncio all'elemento AdContainer, dove possono essere gestiti. Questo non si applica agli annunci lineari su browser non mobile, in quanto il clic sull'annuncio apre il link di clickthrough.

Per implementare la funzionalità di pausa con un clic, aggiungi un gestore dei clic a AdContainer e attiva gli eventi di riproduzione o di 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 negli annunci non lineari

AdsManager mette in pausa il video dei contenuti quando un annuncio è pronto per essere riprodotto, ma questo comportamento non tiene conto degli annunci non lineari, per i quali i contenuti devono continuare a essere riprodotti mentre viene visualizzato l'annuncio. Per supportare gli annunci non lineari, ascolta AdsManager per emettere LOADED. Poi, controlla se l'annuncio è lineare e, in caso contrario, riprendi la riproduzione nell'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à SDK avanzate, consulta le altre guide o i sample su GitHub.