Configura l'SDK IMA

Seleziona la piattaforma: HTML5 Android iOS tvOS

Gli SDK IMA semplificano l'integrazione di annunci multimediali nei siti web e nelle app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server conforme a VAST e gestire la riproduzione degli annunci nelle app. Con gli SDK IMA 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 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 completa, 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 di IMA lato client

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 creare un'istanza di 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, avrai bisogno di:

  • 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 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 che contiene 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 il Apache HTTP Server.

2. Creare un semplice video player

Innanzitutto, modifica index.html per creare un semplice elemento video HTML5, contenuto in un elemento di wrapping elemento, e un pulsante per attivare la riproduzione. L'esempio seguente importa l'SDK IMA e configura l'elemento contenitore AdDisplayContainer. Per maggiori dettagli, consulta rispettivamente i passaggi Importare l'SDK IMA e Creare 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>

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

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

Tieni presente che lo snippet di codice ads.js contiene una chiamata a setUpIMA(), definita nella sezione Inizializzare AdsLoader ed effettuare una richiesta di annunci .

3. Importare l'SDK IMA

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

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

4. Creare il contenitore dell'annuncio

Nella maggior parte dei browser, l'SDK IMA utilizza un elemento contenitore dell'annuncio dedicato per visualizzare sia gli annunci sia gli elementi dell'interfaccia utente correlati agli annunci. Le dimensioni di questo contenitore devono essere tali da sovrapporsi all'elemento video dall' angolo in alto a sinistra. L'altezza e la larghezza degli annunci inseriti in questo contenitore vengono 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' video-container elemento. Quindi, aggiorna il CSS per posizionare l'elemento nell'angolo in alto a sinistra di video-element. Infine, aggiungi la createAdDisplayContainer() funzione per creare l' AdDisplayContainer oggetto utilizzando il nuovo contenitore dell'annuncio div. 

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

5. Inizializzare AdsLoader ed effettuare una richiesta di annunci

Per richiedere annunci, crea un' AdsLoader istanza. Il costruttore AdsLoader accetta un AdDisplayContainer oggetto come input e può essere utilizzato per elaborare 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 altro URL del tag annuncio utilizzando il 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 AdsRequest oggetto, ma riutilizza lo stesso AdsLoader. Per ulteriori informazioni, consulta le domande frequenti sull'SDK IMA.

Ascolta e rispondi agli annunci caricati e agli eventi di errore utilizzando AdsLoader.addEventListener. Ascolta i seguenti eventi:

  • ADS_MANAGER_LOADED
  • AD_ERROR

Per creare i listener onAdsManagerLoaded() e onAdError(), consulta l'esempio seguente: 

/**
 * 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);
}

6. Rispondere agli eventi AdsLoader

Quando il AdsLoader carica correttamente gli annunci, emette un ADS_MANAGER_LOADED evento. Analizza l'evento passato al callback per inizializzare l'oggetto AdsManager. The AdsManager carica i singoli annunci come definiti da la 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();
}

Per maggiori dettagli sui listener impostati nella onAdsManagerLoaded() funzione, consulta le seguenti sottosezioni:

Gestire gli errori di AdsManager

Il gestore degli errori creato per il AdsLoader può fungere anche da gestore degli errori per il AdsManager. Consulta il gestore degli eventi che riutilizza la funzione onAdError(). 

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

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. Allo stesso modo, quando un annuncio viene completato, il AdsManager attiva l' CONTENT_RESUME_REQUESTED evento. 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);

Per le definizioni delle onContentPauseRequested() e onContentResumeRequested() funzioni, consulta 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();
}

Gestire la riproduzione dei contenuti durante gli annunci non lineari

Il AdsManager mette in pausa il video dei contenuti quando un annuncio è pronto per la riproduzione, ma questo comportamento non tiene conto degli annunci non lineari, in cui i contenuti continuano a essere riprodotti mentre l'annuncio è visualizzato. 

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

Per supportare gli annunci non lineari, ascolta l'emissione del LOADED evento da parte di AdsManager. Verifica se l'annuncio è lineare e, in caso contrario, riprendi la riproduzione dell' 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();
  }
}

7. Attivare il 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. Questo 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 dall'overlay dell'annuncio all'elemento AdContainer, dove possono essere gestiti. Questo non si applica agli annunci lineari sui browser non mobile, poiché facendo clic sull'annuncio si apre il link di click-through.

Per implementare il clic per mettere 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();
  }
}

8. Avviare AdsManager

Per avviare la riproduzione degli annunci, inizializza e 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 Riproduci. 

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

9. Supportare il ridimensionamento del player

Affinché gli annunci vengano ridimensionati dinamicamente e corrispondano 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);
  }
});

Questo è tutto. Ora puoi richiedere e visualizzare annunci con l'SDK IMA. Per scoprire di più sulle funzionalità avanzate dell'SDK, consulta le altre guide o gli esempi su GitHub.