Configura l'SDK IMA

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. Avvia un server di sviluppo

Poiché l'SDK IMA carica le dipendenze utilizzando lo stesso protocollo della pagina da cui viene caricato, devi utilizzare un server web per testare la tua 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. L'esempio seguente importa l'SDK IMA e configura l'elemento contenitore AdDisplayContainer. Per maggiori dettagli, consulta rispettivamente i passaggi Importa l'SDK IMA e Crea il contenitore dell'annuncio . 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

index.html
 
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
style.css
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});
ads.js

Aggiungi i tag necessari per caricare i file style.css e ads.js. Quindi, modifica styles.css per rendere il video player adattabile ai dispositivi mobili. Infine, in ads.js, dichiara le variabili e attiva la riproduzione del video quando fai clic sul pulsante di riproduzione.

Tieni presente che lo snippet di codice ads.js contiene una chiamata a setUpIMA(), che è definito nella sezione Inizializza AdsLoader ed effettua una richiesta di annunci .

3. Importa l'SDK IMA

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

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
index.html

4. 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, aggiungi la funzione createAdDisplayContainer() per creare l'oggetto AdDisplayContainer utilizzando il nuovo contenitore annunci div. 

<div id="adContainer"></div>
index.html
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
style.css
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}
ads.js

5. Inizializza AdsLoader ed effettua una richiesta di annunci

Per richiedere gli annunci, crea un'istanza AdsLoader. Il costruttore AdsLoader accetta come input un oggetto AdDisplayContainer e può essere utilizzato per elaborare gli oggetti 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 altro URL del tag annuncio utilizzando lo strumento IMA Video Suite Inspector.

Come best practice, mantieni una sola istanza di AdsLoader per l'intero ciclo di vita di una pagina. Per effettuare ulteriori richieste di annunci, crea un nuovo oggetto AdsRequest, ma riutilizza lo stesso AdsLoader. Per ulteriori informazioni, consulta le domande frequenti sull'SDK IMA.

Monitora e rispondi agli eventi di caricamento degli annunci e di errore utilizzando AdsLoader.addEventListener. Ascolta i seguenti eventi:

  • ADS_MANAGER_LOADED
  • AD_ERROR

Per creare gli ascoltatori onAdsManagerLoaded() e onAdError(), consulta l'esempio riportato di seguito: 

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const 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 = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}
ads.js

6. Rispondere agli eventi AdsLoader

Quando AdsLoader carica gli annunci correttamente, 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.

Assicurati di gestire gli errori che si verificano durante la procedura di caricamento. Se gli annunci non si caricano, assicurati che la riproduzione dei contenuti multimediali continui senza annunci per evitare di interferire con la visualizzazione dei contenuti da parte dell'utente. 

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  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);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}
ads.js

Per ulteriori dettagli sugli ascoltatori impostati nella funzione onAdsManagerLoaded(), consulta le seguenti sottosezioni:

Gestire gli errori AdsManager

Il gestore degli errori creato per AdsLoader può essere utilizzato anche come gestore degli errori per AdsManager. Guarda il gestore eventi che riutilizza la funzione onAdError(). 

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

Gestire gli 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. 

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);
ads.js

Per le definizioni delle funzioni onContentPauseRequested() e onContentResumeRequested(), consulta il seguente esempio: 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}
ads.js

Gestire la riproduzione dei contenuti durante gli annunci non lineari

Il pulsante 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, in cui i contenuti continuano a essere riprodotti mentre viene visualizzato l'annuncio. 

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
ads.js

Per supportare gli annunci non lineari, ascolta AdsManager per emettere LOADED. Controlla se l'annuncio è lineare e, in caso contrario, riprendi la riproduzione nell'elemento video.

Per la definizione della funzione onAdLoaded(), consulta l'esempio seguente. 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}
ads.js

7. Attivare la 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 messa in pausa con un clic, aggiungi la funzione di gestore dei clic adContainerClick() chiamata nel listener on window load. 

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}
ads.js

8. Avvia AdsManager

Per avviare la riproduzione dell'annuncio, avvia e inizia il AdsManager. Per supportare completamente i browser per dispositivi mobili, in cui non puoi riprodurre automaticamente gli annunci, attiva la riproduzione degli annunci dalle interazioni degli utenti con la pagina, ad esempio facendo clic sul pulsante di riproduzione. 

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}
ads.js

9. Supportare il ridimensionamento del player

Affinché gli annunci possano ridimensionarsi dinamicamente e adattarsi alle dimensioni di un video player o alle modifiche dell'orientamento dello schermo, chiama adsManager.resize() in risposta agli eventi di ridimensionamento della finestra. 

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    let width = videoContent.clientWidth;
    let height = videoContent.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});
ads.js

È 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.