Configura l'SDK IMA

Gli SDK IMA semplificano l'integrazione di 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 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 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, consulta il plug-in SDK IMA per Video.js.

Panoramica lato client di IMA

L'implementazione di IMA lato client prevede quattro componenti SDK principali, 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à, inclusi Visualizzazione attiva e Open Measurement.
  • AdsLoader: Un oggetto che richiede annunci e gestisce gli eventi dalle risposte alle richieste di annunci. Devi istanziare 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, 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 degli 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 utilizzando lo stesso protocollo della pagina da cui viene caricato, devi utilizzare un web server 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 che contiene il file index.html, esegui: 
      python -m http.server 8000
  2. In un browser web, vai su http://localhost:8000/.

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

2. Crea 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 attivare la riproduzione. L'esempio seguente importa l'SDK IMA e configura l'elemento container AdDisplayContainer. Per maggiori dettagli, consulta 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 è definita nella sezione Inizializza AdsLoader ed effettua una richiesta di annunci .

3. Importa l'SDK IMA

Successivamente, 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 di annunci dedicato per visualizzare sia gli annunci sia gli elementi dell'interfaccia utente correlati agli annunci. Questo contenitore deve essere dimensionato per sovrapporsi all'elemento video dall'angolo in alto a sinistra. L'altezza e la larghezza degli annunci inseriti in questo contenitore sono impostate dall'oggetto adsManager, quindi non è necessario impostare questi valori manualmente.

Per implementare questo elemento contenitore dell'annuncio, crea innanzitutto un nuovo div all'interno dell'elemento video-container. Poi, 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 dell'annuncio 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 annuncio

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

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

Ascolta 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 i listener onAdsManagerLoaded() e onAdError(), consulta il seguente esempio: 

/**
 * 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&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 correttamente gli annunci, 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 eventuali errori che si verificano durante il processo di caricamento. Se gli annunci non vengono caricati, 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 maggiori dettagli sui listener impostati nella funzione onAdsManagerLoaded(), consulta le seguenti sottosezioni:

Gestire gli errori AdsManager

Il gestore degli errori creato per AdsLoader può fungere anche da gestore degli errori per AdsManager. Vedi 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 pausa

Quando AdsManager è pronto per inserire un annuncio da visualizzare, attiva l'evento CONTENT_PAUSE_REQUESTED. Gestisci questo evento attivando una 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 sottostante. 

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(), vedi l'esempio seguente: 

/**
 * 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 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 l'annuncio viene visualizzato. 

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

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

Per la definizione della funzione onAdLoaded(), vedi 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à di clic per mettere in pausa 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 passa tutti i clic non gestiti da IMA dalla sovrapposizione dell'annuncio all'elemento AdContainer, dove possono essere gestiti. Ciò non si applica agli annunci lineari sui browser non mobile, in quanto il clic sull'annuncio apre il link clickthrough.

Per implementare la funzionalità Fai clic e metti in pausa, aggiungi la funzione di gestione dei clic adContainerClick() chiamata nel listener di caricamento della finestra. 

/**
 * 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 AdsManager. Per supportare completamente i browser mobile, in cui non è possibile riprodurre automaticamente gli annunci, attiva la riproduzione degli annunci dalle interazioni dell'utente 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é le dimensioni degli annunci vengano modificate dinamicamente in modo che corrispondano a quelle di un video player o alle modifiche all'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à avanzate dell'SDK, consulta le altre guide o gli esempi su GitHub.