Per iniziare

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

Questa guida illustra come integrare l'SDK IMA in una semplice app per video player. Se desideri visualizzare o seguire un'integrazione di esempio completata, scarica semplice esempio tratto da GitHub. Se un player HTML5 con l'SDK preintegrato, consulta la SDK IMA SDK per Video.js.

Panoramica lato client IMA

L'implementazione dell'SDK IMA sul lato client riguarda quattro componenti SDK principali, illustrati in questo guida:

  • AdDisplayContainer: Un oggetto contenitore in cui vengono visualizzati gli annunci.
  • AdsLoader: Un oggetto che richiede annunci e gestisce gli eventi provenienti dalle risposte alle richieste di annunci. Dovresti soltanto creare un'istanza per 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, parametri aggiuntivi, come le dimensioni degli annunci.
  • AdsManager: Un oggetto che contiene la risposta alla richiesta di annunci, controlla la riproduzione dell'annuncio e rimane in ascolto dell'annuncio eventi attivati dall'SDK.

Prerequisiti

Prima di iniziare, ti serviranno:

  • Tre file vuoti:
    • index.html
    • style.css
    • ads.js
  • Python installato sul computer o su 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 viene caricato, devi utilizzare un server web per testare l'app. Il modo più semplice per iniziare uno sviluppo locale è usare il server integrato di Python.

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

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

2. Creare un video player semplice

In primo luogo, modifica index.html per creare un semplice elemento video HTML5 da inserire in un wrapping e un pulsante per attivare la riproduzione. Aggiungi anche i tag necessari per caricare style.css e ads.js. Poi modifica il file styles.css per creare il video player. adattabile per i dispositivi mobili. Infine, in ads.js, attiva la riproduzione del video durante la riproduzione. viene fatto clic sul pulsante.

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) dovresti essere in grado di vedere l'elemento video e il video dovrebbe avviarsi quando fai clic sul pulsante di riproduzione.

3. Importa l'SDK IMA

In seguito, 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 di eventi che attivano la funzione 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 l'elemento video e adsManager per rendere la pagina adattabile ai dispositivi mobili
di Gemini Advanced. di Gemini Advanced. 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 degli annunci

Nella maggior parte dei browser, l'SDK IMA utilizza un elemento contenitore di annunci dedicato per visualizzare sia gli annunci che elementi dell'interfaccia utente relativi agli annunci. Questo contenitore deve essere dimensionato in modo da sovrapporre l'elemento video dal nell'angolo in alto a sinistra. L'altezza e la larghezza degli annunci inseriti in questo contenitore vengono impostate dal valore-chiave adsManager, quindi non è necessario impostare questi valori manualmente.

Per implementare questo elemento del contenitore di annunci, crea prima un nuovo div all'interno dell'elemento Elemento video-container. Quindi, aggiorna il CSS per posizionare l'elemento in alto a sinistra angolo di video-element. Infine, definisci una variabile per il container all'interno Funzione initializeIMA() 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 una serie di annunci, crea un'istanza ima.AdsLoader. Questa istanza prende un oggetto AdDisplayContainer come input e può essere utilizzato per elaborare ima.AdsRequest oggetti 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 la proprietà IMA Video Suite Inspector.

Come best practice, gestisci una sola istanza di ima.AdsLoader per l'intera ciclo di vita di una pagina. Per effettuare altre richieste di annunci, crea una nuova ima.AdsRequest ma riutilizza lo stesso ima.AdsLoader. Per ulteriori informazioni, consulta 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 AdsManager oggetto. L'elemento AdsManager carica i singoli annunci come definito dalla risposta all'annuncio URL del tag.

Inoltre, assicurati di gestire eventuali errori che possono verificarsi durante il processo di caricamento. Se gli annunci non carica, assicurati che la riproduzione dei contenuti multimediali continui, senza annunci, in modo da non interferire con il l'esperienza 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. Avviare AdsManager

Per avviare la riproduzione dell'annuncio, devi avviare AdsManager. Per il supporto completo dei dispositivi mobili browser, questo deve 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. Rendere AdsManager adattabile

Per fare in modo che gli annunci vengano ridimensionati in modo dinamico per adattarsi alle dimensioni del video player, se lo schermo cambia le dimensioni o l'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 tenere traccia delle modifiche dello stato, attivare la riproduzione e la messa in pausa del video e registrare gli errori.

Gestione degli errori

Il gestore degli errori creato per AdsLoader può fungere da gestore degli errori per i campi 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);
}

...

Attivare eventi di riproduzione e pausa

Quando lo AdsManager è pronto per inserire un annuncio per la Rete Display, attiva la Evento CONTENT_PAUSE_REQUESTED. Per gestire questo evento, attiva una pausa nella nel video player sottostante. Analogamente, quando un annuncio viene completato, AdsManager attiva la Evento CONTENT_RESUME_REQUESTED. Gestisci questo evento riavviando la riproduzione sul video di 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();
}

Attivare la modalità "Fai clic per mettere in pausa" sui dispositivi mobili

Poiché l'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 tutti i clic che non sono gestiti dall'IMA dall'overlay dell'annuncio all'elemento AdContainer, dove possono essere gestiti. Questo non vale per gli annunci lineari su browser non mobile, in quanto facendo clic sull'annuncio si apre la di clickthrough.

Per implementare la funzionalità "clic per mettere in pausa", aggiungi un gestore dei clic a AdContainer e attiva la riproduzione. o mettere in pausa gli eventi 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 un annuncio è pronto per la riproduzione, ma questo comportamento non tiene conto degli annunci non lineari, i cui contenuti devono continuare a essere riprodotti mentre il dell'annuncio. Per supportare gli annunci non lineari, attendi che AdsManager emetta il codice Evento LOADED. Poi, controlla se l'annuncio è lineare e, in caso contrario, riprendi la riproduzione sulla 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 stai richiedendo e mostrando gli annunci con l'SDK IMA. Per saperne di più funzioni avanzate dell'SDK, consulta le altre guide o su GitHub.