Interruzioni pubblicitarie

Panoramica

L'SDK del ricevitore web offre il supporto nativo per le interruzioni pubblicitarie e gli annunci companion all'interno di un determinato stream multimediale. Offre due modi per incorporare le interruzioni pubblicitarie nel ricevitore: stitching lato client e lato server utilizzando interruzioni e clip di interruzione.

Prima di iniziare lo sviluppo delle interruzioni pubblicitarie, assicurati di configurare un destinatario web personalizzato. L'API Cast SDK Breaks garantisce che gli utenti abbiano un'esperienza coerente su tutti i dispositivi compatibili con Google Cast quando gli annunci fanno parte della riproduzione.

Avviso: l'utilizzo dell'API Ad Breaks non è attualmente supportato con l'API Live.

In questa guida, un'interruzione si riferisce a un intervallo di riproduzione che contiene uno o più annunci o bumper e ogni annuncio o bumper viene definito clip di interruzione.

Questo diagramma mostra due interruzioni pubblicitarie, ciascuna contenente due annunci:

Nota: i segmenti visualizzati sono delle interruzioni e dei relativi clip in una sequenza temporale espansa. La barra di avanzamento rappresenta sempre la sequenza temporale dei contenuti, indipendentemente dal fatto che venga utilizzata o meno l'unione lato client o server.

Eventi

La tabella seguente descrive gli eventi che vengono attivati quando vengono rilevate le interruzioni durante la riproduzione.

Evento Pausa	Descrizione
BREAK_STARTED	Attivato quando inizia il caricamento del primo clip di un'interruzione. L'evento è cast.framework.events.BreaksEvent.
PAUSA_FINE	Attivato quando termina l'ultimo clip di un'interruzione. L'evento è cast.framework.events.BreaksEvent. Nota:questo evento si attiva anche se un utente salta l'ultimo clip di un'interruzione per terminarla.
BREAK_CLIP_CARICAMENTO	Attivato quando inizia il caricamento di un clip di interruzione. L'evento è cast.framework.events.BreaksEvent.
BREAK_CLIP_INIZIATO	Attivato quando inizia un clip di interruzione. L'evento è cast.framework.events.BreaksEvent.
BREAK_CLIP_ENDED	Attivato quando termina un clip di interruzione. L'evento è cast.framework.events.BreaksEvent. Nota:questo evento si attiva anche se un utente salta un clip di interruzione. Controlla la proprietà endedReason di BreaksEvent. Per capire per quanto tempo è stato guardato il clip della pausa, controlla getBreakClipCurrentTimeSec e getBreakClipDurationSec di PlayerManager.

Questi eventi possono essere utilizzati per l'analisi e il monitoraggio della riproduzione degli annunci. Quando vengono utilizzati VMAP (Video Multiple Ad Playlist) e VAST (Video Ad Serving Template), gli eventi di monitoraggio standard forniti nelle risposte vengono inviati automaticamente dall'SDK.

Durante la riproduzione di un'interruzione, l'SDK Ricevitore web trasmette MediaStatus con breakStatus a tutti i mittenti connessi. I mittenti possono utilizzare queste informazioni per aggiornare le UI e eliminare qualsiasi operazione di ricerca.

L'SDK del ricevitore web offre due modi per incorporare le interruzioni pubblicitarie nel ricevitore: stitching lato client e lato server.

stitching di annunci lato client

Per l'unione di annunci lato client, nota anche come non incorporata, le informazioni necessarie sugli annunci devono essere specificate con gli oggetti Break e BreakClip quando viene caricato il contenuto multimediale. Lo snippet che segue è un esempio di una funzione che aggiunge interruzioni pre-roll, mid-roll e post-roll, in cui i riferimenti a third_party e ai suoi metodi sono esempi di funzioni di supporto che uno sviluppatore potrebbe avere nella sua app. Lo snippet mostra anche come possono essere attivati gli eventi di monitoraggio quando un utente guarda un clip di interruzione fino al completamento ascoltando l'evento BREAK_CLIP_ENDED e controllando il valore di endedReason.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    title: third_party.getBreakClipTitle('bc1'),
    contentId: third_party.getBreakClipUrl('bc1'),
    contentType: third_party.getBreakClipContentType('bc1'),
    posterUrl: third_party.getBreakClipPosterUrl('bc1')
  },
  {
    id: 'bc2'
    ...
  },
  {
    id: 'bc3'
    ...
  },
  {
    id: 'bc4'
    ...
  }];
  mediaInformation.breaks = [
  {
    id: 'b1',
    breakClipIds: ['bc1', 'bc2'],
    position: 0  //pre-roll position
  },
  {
    id: 'b2',
    breakClipIds: ['bc3'],
    position: 10*60 //ten minutes
  },{
    id: 'b3',
    breakClipIds: ['bc4'],
    position: -1  //post-roll position (-1 is only valid client stitching; for server-side ad stitching, exact position is required)
  }];
}

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.addEventListener(cast.framework.events.EventType.BREAK_CLIP_ENDED, function(event){
  if(event.endedReason === cast.framework.events.EndedReason.END_OF_STREAM){
    //call your ad tracking code here for break clip watched to completion
  }
});


playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    loadRequestData => {
      addBreakToMedia(loadRequestData.media);
      return loadRequestData;
    });
context.start();

Nota: il callback a setMessageInterceptor include un oggetto LoadRequestData come argomento.

Annunci VAST

L'SDK del ricevitore web supporta gli annunci VAST standard IAB. Per includere gli annunci VAST nei contenuti multimediali, crea un oggetto vastAdsRequest e assegnalo alla proprietà vastAdsRequest di una BreakClip. L'oggetto vastAdsRequest deve avere la proprietà adsResponse o la proprietà adTagUrl.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    vastAdsRequest:{
      adTagUrl: 'https://castsample.com/vast?rand=' + Math.floor(Math.random()* 10000)
    }
  }];
}

L'SDK Web Receiver invia una richiesta al tag adTagUrl specificato e analizza la risposta XML per generare un oggetto BreakClip. Di seguito è riportato un esempio di un oggetto BreakClip generato dal nostro SDK.

{
  "id": "GENERATED:0",
  "contentId": "https://file.mp4",
  "contentType": "video/mp4",
  "title": "Preroll",
  "duration": 10,
  "clickThroughUrl": "https://click"
}

Annunci VMAP

L'SDK Web Receiver supporta anche lo standard VMAP di IAB. Quando viene fornito un VMAP, l'SDK Cast analizza la risposta VMAP e genera gli oggetti Break per le voci <AdBreak> specificate nella risposta. Genera anche l'oggetto BreakClips appropriato con un oggetto vastAdsRequest per ogni voce <AdSource> fornita in VMAP. Per utilizzare VMAP per inserire annunci nei contenuti, crea un oggetto vastAdsRequest e assegnalo alla proprietà vmapAdsRequest dell'oggetto MediaInformation come parte della richiesta di caricamento.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.vmapAdsRequest = {
    adTagUrl: 'https://castsample.com/vmap?rand=' + Math.floor(Math.random()* 10000)
  };
}

Nota: se viene effettuato un vmapAdsRequest congiuntamente alle voci di interruzione/interruzione manuale, vmapAdsRequest verrà ignorato.

stitching di annunci lato server

Per l'unione del lato server, nota anche come annunci incorporati, il server dovrebbe fornire un singolo stream contenente sia i contenuti multimediali principali sia gli annunci. In questo caso, lo sviluppatore è tenuto a fornire i valori duration e contentType dei BreakClip. contentUrl è omesso. Inoltre, isEmbedded deve essere impostato su true.

Nota: l'SDK Cast utilizza la proprietà isEmbedded per determinare se BreakClip deve essere aggiunto dinamicamente alla sequenza temporale o se fa parte dei contenuti esistenti. Per impostazione predefinita, l'SDK CAF presuppone che l'elemento BreakClip non sia incorporato e deve essere aggiunto dinamicamente alla sequenza temporale.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    title: third_party.getBreakClipTitle('bc1'),
    posterUrl: third_party.getBreakClipPosterUrl('bc1'),
    duration: third_party.getBreakClipDuration('bc1')
  },
  {
    id: 'bc2'
    ...
  },
  {
    id: 'bc3'
    ...
  },
  {
    id: 'bc4'
    ...
  }];
  mediaInformation.breaks = [
  {
    id: 'b1',
    breakClipIds: ['bc1', 'bc2'],
    position: 0,
    isEmbedded: true
  },
  {
    id: 'b2',
    breakClipIds: ['bc3', 'bc4'],
    position: 10*60,
    isEmbedded: true
  }];
}

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    loadRequestData => {
      addBreakToMedia(loadRequestData.media);
      return loadRequestData;
    });
context.start();

Nota: il callback a setMessageInterceptor prende in oggetto un oggetto LoadRequestData.

Comportamento delle interruzioni

Comportamento predefinito per le interruzioni

1. Una volta avviata, l'interruzione verrà contrassegnata come isWatched. Se poi un utente esegue lo scorrimento a un punto prima dell'interruzione, i contenuti iniziano la riproduzione come di consueto e l'interruzione viene successivamente saltata come se fosse stata precedentemente guardato.
2. Se un utente scorra oltre una o più interruzioni senza guardarle, viene riprodotta l'ultima interruzione non riprodotta tra le posizioni seekFrom e seekTo prima dell'inizio della riproduzione dei contenuti.

Comportamento interruzione personalizzato

default behavior per interruzioni e clip di interruzione può essere modificato utilizzando i metodi setBreakClipLoadInterceptor e setBreakSeekInterceptor nell'oggetto BreakManager.

Nota: se esegui un'operazione di ricerca dopo un completamento interruzione, assicurati che l'oggetto playerState di MediaStatus sia stato modificato in cast.framework.messages.PlayerState.PLAYING prima di eseguire l'operazione di ricerca.

setBreakClipLoadInterceptor

setBreakClipLoadInterceptor viene chiamato prima dell'interruzione. Questa funzione viene richiamata una volta per clip di interruzione. Passa un oggetto BreakClip nella funzione di callback.

Ad esempio, se è presente un'interruzione pre-roll, setBreakClipLoadInterceptor viene richiamato per l'interruzione pre-roll all'inizio della riproduzione. Subito dopo la fine della riproduzione del pre-roll, viene chiamata setBreakClipLoadInterceptor per la prossima interruzione.

Se nella funzione di callback non viene restituito nulla o nulla, il clip di interruzione viene saltato. Tutti gli intercettori di una pausa vengono chiamati immediatamente.

Con setBreakClipLoadInterceptor, è possibile modificare un oggetto BreakClip prima che inizi la riproduzione.

setBreakSeekInterceptor

setBreakSeekInterceptor viene attivato dopo un'operazione di ricerca e passa un oggetto BreakSeekData alla funzione di callback. L'oggetto BreakSeekData contiene un array di Interruzioni le cui posizioni sono definite tra il tempo di riproduzione attuale e quello di ricerca (ad esempio seekFrom e seekTo). Dopo un'operazione di ricerca in avanti, il comportamento predefinito prevede la riproduzione dell'ultima interruzione non riprodotta prima dell'ora di seekTo. Quando la riproduzione è terminata, la riproduzione dei contenuti riprende dalla posizione seekTo.

Questo intercettore consente di modificare gli oggetti BreakClip nelle rispettive interruzioni.

Se vuoi personalizzare il comportamento, puoi implementare setBreakSeekInterceptor per sostituire default behavior. Se l'opzione setBreakSeekInterceptor è implementata, devi specificare esplicitamente le interruzioni da riprodurre.

• Se il valore setBreakSeekInterceptor restituisce null o non viene restituito nulla, l'interruzione viene saltata.
• Se viene restituito lo stesso oggetto passato nella funzione di callback, l'oggetto default behavior viene sostituito e tutte le interruzioni vengono riprodotte. Inoltre, se un utente esegue il passaggio a un punto precedente, vedrà le interruzioni anche se in precedenza le aveva guardate. Se setBreakSeekInterceptor non è implementato, le interruzioni già guardate vengono ignorate.

Creazione di clip di pausa ignorabili

Per rendere ignorabile un clip di interruzione, specifica quanti secondi attendere prima che il clip di interruzione sia ignorabile nell'oggetto BreakClip.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(media) {
  media.breakClips = [
  {
    id: 'bc1',
    ...
    whenSkippable: 10 //to allow user to skip break clip from sender after 10 seconds
  }];
}

Nota: (solo mittente web) oltre a implementare lo snippet riportato sopra, sarà necessario aggiungere code al lato mittente per consentire a un utente di saltare un annuncio. Questo non è necessario sulle piattaforme per dispositivi mobili poiché la funzionalità è fornita dall'SDK.

Annunci con salto automatico

Gli annunci possono essere saltati automaticamente senza interazione da parte dell'utente. Esistono due modi per saltare gli annunci:

1. Se imposti la proprietà isWatched di un'interruzione su vero, questa viene saltata automaticamente.

   playerManager.addEventListener(cast.framework.events.category.CORE, function(event){
     if(event.type === cast.framework.events.EventType.PLAYER_LOADING){
       let breaks = playerManager.getBreaks();
       for(let i in breaks){
         breaks[i].isWatched = true;
       }
     }
   });

2. È possibile ignorare un elemento BreakClip restituisce un valore null nella funzione di callback setBreakClipLoadInterceptor.

   playerManager.getBreakManager().setBreakClipLoadInterceptor(breakClip => {
     return null;
   });