Interruzioni pubblicitarie

Panoramica

L'SDK Web Receiver presenta il supporto nativo per le interruzioni pubblicitarie e gli annunci companion all'interno di un determinato stream multimediale. Fornisce le API per impostare la posizione dell'annuncio, l'origine annuncio e il comportamento delle interruzioni pubblicitarie e i clip di interruzione associati. In questa guida, il simbolo Break fa riferimento a un intervallo di riproduzione contenente uno o più annunci o bumper e ogni annuncio o bumper è denominato BreakClip. Queste interruzioni sono associate ai contenuti multimediali caricati o in riproduzione.

Tipi di annunci

L'SDK Web ricevir supporta l'inserimento di annunci lato client (CSAI) e l'inserimento di annunci con stitching (SSAI) server. Gli annunci con stitching client possono essere impostati manualmente dall'applicazione o estratti dai file modello VAST e VMAP. Gli annunci uniti al server devono essere specificati manualmente prima del caricamento dei contenuti come annunci incorporati o in modo dinamico durante la riproduzione dei contenuti come annunci incorporati. Di seguito sono descritte in dettaglio le implementazioni per ciascuno di questi tipi di annunci.

stitching manuale con client

Un'interruzione pubblicitaria manuale con stitching client è un tipo di interruzione pubblicitaria che viene unito dal client e specificato manualmente dall'applicazione utilizzando le API SDK. Questo tipo di annuncio non è incorporato nello stream dei contenuti principali. L'elemento BreakClip deve fornire contentId, ovvero un URL che rimanda al contenuto dell'annuncio, contentType che descrive il formato del contenuto dell'annuncio e title.

Nota: in alcuni casi è necessario fornire ulteriori informazioni sul formato dei contenuti degli annunci nella proprietà hlsSegmentFormat per gli annunci HLS riprodotti da MPL. Analogamente alla guida al supporto del formato dei segmenti dei contenuti principali, questa proprietà comunica al player il formato del contenitore previsto per i segmenti di annunci sottostanti.

Per Break devono essere impostati isEmbedded e expanded sul valore predefinito false. L'elemento position può essere impostato su un'interruzione pubblicitaria pre-roll, mid-roll o post-roll (scopri di più nella sezione sul posizionamento dell'interruzione). Quando prepari l'annuncio per la riproduzione, l'SDK Web ricevir genera un'altra istanza del player per caricare e riprodurre i contenuti dell'annuncio. Queste interruzioni richiedono un stitched timeline e devono essere aggiunte in modo statico (scopri di più nella sezione Inserimento di annunci). L'esempio riportato di seguito mostra un'implementazione di base di un annuncio manuale con stitching del client:

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

VAST

L'SDK Web Receiver supporta l'aggiunta di annunci VAST (Video Ad Serving Template) standard IAB. Se fornito, il modello XML viene analizzato per generare un clip di interruzione con stitching client successivo all'inizio dell'interruzione.

Per creare un annuncio VAST, l'app del destinatario deve creare un elemento VastAdsRequest e specificarlo nella proprietà BreakClip vastAdsRequest. Per l'oggetto VastAdsRequest deve essere definita la proprietà adsResponse (una rappresentazione stringa del modello XML stesso) o la proprietà adTagUrl (l'URL in cui è ospitato il modello XML). Se l'URL viene specificato, l'SDK gestirà il recupero del modello. L'elemento Break incapsulante segue le convenzioni per gli annunci con stitching client. Questi annunci possono essere aggiunti insieme ad altri annunci manuali uniti al client nella stessa interruzione o in interruzioni separate per gli stessi contenuti. Il seguente esempio mostra un'implementazione di base di un annuncio VAST:

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

Quando viene inserito un valore Break che contiene un valore BreakClip VAST, l'SDK Web ricevitore recupera e analizza il modello. Durante l'analisi, l'SDK genera un nuovo BreakClip e lo completa con i valori estratti dal modello, come contentId, contentType, title, duration, whenSkippable e clickThroughUrl. Il valore id per il clip di interruzione generato è impostato su GENERATED:N, dove N è un numero intero che viene incrementato di 1 per ogni nuovo clip di interruzione VAST creato a partire dal giorno 0. L'annuncio generato viene quindi aggiunto all'array BreakClip. Il valore id di ogni clip di interruzione VAST nell'elemento Break corrente viene sostituito con l'elemento id del clip di interruzione generato corrispondente. Gli snippet riportati di seguito illustrano le modifiche nei messaggi MEDIA_STATUS attinenti agli annunci prima e dopo l'inserimento di questa interruzione.

Nota: gli array BreakClip e Break sono aggiornati e accessibili in BreakManager. Queste informazioni sono incorporate nel MEDIA_STATUS, che viene trasmesso ai mittenti.

Informazioni su Break e BreakClip prima di inserire un'interruzione con gli annunci VAST.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

Informazioni su Break e BreakClip dopo aver inserito un'interruzione con gli annunci VAST.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

VMAP

L'SDK Web ricevir supporta lo standard VMAP (Video Multiple Ad Playlist) dello IAB. Quando viene fornito un VMAP, l'SDK Web ricevitore analizzerà la risposta VMAP e genererà oggetti Break con stitching client per tutte le voci <AdBreak> nella risposta. Inoltre, genererà anche il valore BreakClips appropriato con un oggetto vastAdsRequest per ogni voce <AdSource> fornita in VMAP. Per abilitare VMAP per l'inserimento di annunci nei tuoi contenuti, l'applicazione deve creare un oggetto VastAdsRequest e assegnarlo alla proprietà vmapAdsRequest di MediaInformation in LoadRequestData. Questi annunci devono essere inseriti in modo statico (per saperne di più, consulta la sezione sull'inserimento di annunci). Di seguito è riportato uno snippet che descrive la creazione di una richiesta VMAP.

Nota: l'impostazione manuale degli annunci Break e BreakClip in combinazione con gli annunci VMAP sostituirà la richiesta di annuncio VMAP. Di conseguenza, l'SDK eliminerà la richiesta di annuncio VMAP e per impostazione predefinita utilizzerà gli annunci specificati manualmente in MediaInformation.

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

incorporata

Un'interruzione pubblicitaria incorporata è un tipo di interruzione pubblicitaria che viene unito lato server nello stream del contenuto principale. La durata di Break viene sottratta dalla durata del contenuto principale durante il calcolo del tempo multimediale.

L'BreakClip deve fornire il duration del contenuto dell'annuncio e i title. L'elemento Break deve essere isEmbedded impostato su true e expanded su false. L'elemento position può essere impostato come interruzione pubblicitaria pre-roll o mid-roll. Le interruzioni pubblicitarie post-roll sono supportate con valori position esatti positivi. Per ulteriori informazioni, consulta la sezione Posizionamento dell'interruzione. Quando viene attivata la riproduzione dell'annuncio, l'SDK Web ricevir continua la riproduzione dello stream mentre i segmenti di annunci sono incorporati al suo interno. Non esiste un meccanismo di caricamento aggiuntivo per questo tipo di annuncio. I metadati dell'annuncio pertinenti vengono mostrati all'utente quando la testina di riproduzione rientra nell'intervallo di tempo di interruzione. Queste interruzioni richiedono un embedded timeline e devono essere aggiunte in modo statico (scopri di più nella sezione sull'inserimento di annunci). L'esempio riportato di seguito mostra un'implementazione di base di un annuncio embedded.

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

incorporato espanso

L'interruzione pubblicitaria espansa incorporata è un tipo di interruzione pubblicitaria che viene unito lato server allo stream dei contenuti principali. La durata di Break è inclusa nella durata del contenuto principale durante il calcolo del tempo multimediale.

L'BreakClip deve fornire il duration del contenuto dell'annuncio e i title. L'elemento Break deve essere isEmbedded impostato su true e expanded su true. L'elemento position può essere impostato come interruzione pubblicitaria pre-roll o mid-roll. Le interruzioni pubblicitarie post-roll sono supportate con valori position positivi. Per ulteriori informazioni, consulta la sezione Posizionamento dell'interruzione. Quando viene attivata la riproduzione dell'annuncio, l'SDK Web ricevir continua la riproduzione dello stream mentre i segmenti di annunci sono incorporati al suo interno. Non esiste un meccanismo di caricamento aggiuntivo per questo tipo di annuncio. I metadati dell'annuncio pertinenti vengono mostrati all'utente quando la testina di riproduzione rientra nell'intervallo di tempo di interruzione. Queste interruzioni richiedono un embedded timeline e possono essere aggiunte in modo statico o dinamicamente (scopri di più nella sezione Inserimento di annunci). Il seguente esempio mostra un'implementazione di base di un annuncio embedded expanded:

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

Tipi di sequenza temporale dei giocatori

Durante la creazione di un'istanza del player, l'SDK Web Receiver seleziona un tipo di sequenza temporale per supportare la riproduzione degli annunci durante la riproduzione dei contenuti. Ogni sequenza temporale consente di aggiungere determinati tipi di interruzioni pubblicitarie. Il tipo di sequenza temporale è determinato dai tipi di annunci presenti durante il tempo di caricamento nella MediaInformation della LoadRequestData. Se sono presenti interruzioni pubblicitarie incorporate, viene selezionata la sequenza temporale embedded. Se sono presenti interruzioni pubblicitarie collegate al client, viene selezionata la sequenza temporale stitched. Se non ci sono annunci, l'SDK utilizza per impostazione predefinita la sequenza temporale embedded. Una volta selezionata, la sequenza temporale non può essere modificata per l'elemento multimediale corrente. La tabella seguente fornisce una descrizione dettagliata di ciascuna sequenza temporale.

Tipo di sequenza temporale	Descrizione
sequenza temporale incorporata	Una rappresentazione del tempo multimediale che supporta gli annunci incorporati nei contenuti principali (interruzioni pubblicitarie espanse incorporate e incorporate). In presenza di un'interruzione pubblicitaria non espansa, la sua durata viene sottratta dalla durata totale dei contenuti. D'altra parte, quando è presente un'interruzione pubblicitaria estesa, il relativo tempo è considerato parte dei contenuti principali.
sequenza temporale unita	Una rappresentazione del tempo media che supporta gli annunci provenienti da file multimediali esterni (interruzioni pubblicitarie con stitching manuale e client, VAST e VMAP). Una volta aggiunta, la durata dell'interruzione pubblicitaria non fa parte della durata dei contenuti principali.

Le immagini da 1 a 3 riportate di seguito illustrano alcuni contenuti con diversi tipi di annunci e i rispettivi valori nella sequenza temporale. Il contenuto è configurato con un'interruzione pre-roll contenente due clip di interruzione e interruzioni mid-roll e post-roll che contengono un singolo clip di interruzione. Sotto ogni figura sono allineati il tempo reale dall'inizio della riproduzione dei contenuti, il tempo multimediale dei contenuti principali e l'ora del clip di interruzione attualmente in riproduzione.

Figura 1: la sequenza temporale che rappresenta alcuni contenuti e le relative tre interruzioni pubblicitarie fissate al client.

Figura 2: la sequenza temporale che rappresenta alcuni contenuti e le tre interruzioni pubblicitarie incorporate con stitching del server.

Figura 3: la sequenza temporale che rappresenta alcuni contenuti e le tre interruzioni pubblicitarie espanse incorporate con stitching del server.

Interrompi posizionamento

L'SDK Web Receiver consente agli sviluppatori di specificare dove posizionare le interruzioni pubblicitarie impostando la proprietà position di Break. Questo valore corrisponde al tempo di riproduzione dei contenuti principali e può essere utilizzato per creare interruzioni pubblicitarie pre-roll, mid-roll e post-roll. Questi parametri sono definiti come segue:

Posizione di rottura	Descrizione
pre-roll	Un'interruzione pubblicitaria riprodotta prima dei contenuti principali. Per farlo, si imposta breakPosition su 0
mid-roll	Un'interruzione pubblicitaria riprodotta durante la riproduzione dei contenuti. Ciò è indicato impostando breakPosition su un'ora in cui l'inizio dell'interruzione è maggiore dell'inizio dei contenuti principali e l'ora di fine dell'interruzione è inferiore all'ora di fine del contenuto principale.
post-roll	Un'interruzione pubblicitaria riprodotta dopo i contenuti principali. Per farlo, imposta breakPosition su -1 per le sequenze temporali unite. Per le sequenze temporali incorporate, il valore breakPosition deve essere impostato sulla durata dei contenuti principali sottratta dalla durata dell'interruzione. Non supportata per i contenuti dal vivo.

Matrice interoperabilità

Come punto di riferimento rapido, la Tabella 1 mostra una panoramica dei tipi di annunci e della loro compatibilità con le funzionalità correlate agli annunci.

Tabella 1: matrice di interoperabilità degli annunci

Supporto delle funzionalità	annuncio manuale con stitching client	VAST	VMAP	annuncio incorporato	annuncio espanso incorporato
compatibile con	VAST	stitching manuale con client	N/A	incorporato espanso	incorporata
sequenza temporale	con cucitura	con cucitura	con cucitura	incorporata	incorporata
inserimento di annunci	static	static	static	static	statico, dinamico
rimozione degli annunci
annuncio pre-roll
annuncio mid-roll
annuncio post-roll
ignora annuncio
intercettore di ricerca di interruzione
intercettore caricamento clip di interruzione

Eventi

Quando si verificano eventi di interruzione chiave, l'SDK Cast invierà eventi di tipo BreaksEvent. Un'app destinatario può iscriversi utilizzando l'API PlayerManager addEventListener.

Questi eventi possono essere utilizzati per l'analisi e il monitoraggio della riproduzione degli annunci. Quando si utilizzano gli annunci VMAP (Video Multiple Ad Playlist) e VAST (Video Ad Serving Template), qualsiasi evento di monitoraggio standard fornito nelle risposte viene inviato automaticamente dall'SDK.

I tipi di eventi sono elencati nella Tabella 2 insieme a una descrizione dettagliata quando vengono attivati.

Figura 4: ciclo di vita degli eventi di interruzione.

Tabella 2: eventi di interruzione e relative descrizioni.

Evento di interruzione	Descrizione
BREAK_STARTED	Attivato quando il tempo multimediale corrente dei contenuti principali corrisponde al valore position di un'interruzione non guardata.
BREAK_CLIP_LOADING	Attivato solo quando inizia il caricamento di un clip di interruzione della sequenza temporale unita.
BREAK_CLIP_STARTED	Attivato quando avvia la riproduzione di un clip di interruzione.
BREAK_CLIP_ENDED	Attivato al termine di un clip di interruzione. Il campo endedReason verrà compilato per le seguenti circostanze: Un clip di interruzione della sequenza temporale unita riprodotto interamente. Un clip di interruzione della sequenza temporale unito passa a un altro clip di interruzione. Qualsiasi clip di interruzione viene saltato. L'ultimo clip dell'interruzione è stato riprodotto interamente in un'interruzione incorporata post-roll. Si è verificato un errore.
BREAK_ENDED	Attivato al termine dell'ultimo clip di interruzione di un'interruzione.

Inserimento di annunci

L'SDK Cast consente alle applicazioni di inserire e rimuovere annunci in momenti diversi di una sessione di trasmissione. I due tipi di inserimento di annunci sono statici e dinamici. L'inserimento di annunci statici richiede che gli annunci siano specificati nel campo LoadRequestData prima della creazione del player. L'inserimento di annunci dinamici utilizza l'API BreakManager addBreak per inserire interruzioni nei contenuti già caricati. Ogni tipo di metodo di inserimento è compatibile con determinati tipi di annunci. Nella matrice di interoperabilità è disponibile una panoramica della compatibilità.

Inserimento di annunci statici

L'inserimento di annunci statici è caratterizzato dall'aggiunta dei metadati pertinenti dell'annuncio prima della creazione del player. Queste informazioni sono fornite nel MediaInformation del LoadRequestData. Ad esempio, può essere impostato nella richiesta di carico originale di un mittente connesso oppure può essere inserito dall'applicazione Ricevitore web intercettando la richiesta LOAD. Una volta che LoadRequestData viene restituito all'SDK Web Receiver per l'elaborazione, viene creato il player. Leggi ulteriori informazioni sul caricamento dei contenuti multimediali. L'esempio riportato di seguito mostra un annuncio manuale con stitching del client che viene aggiunto nell'intercettatore delle richieste LOAD.

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

Inserimento di annunci dinamici

L'inserimento di annunci dinamici è caratterizzato dall'impostazione di un'interruzione pubblicitaria durante la riproduzione dei contenuti. A questo scopo, ottieni un'istanza di BreakManager e chiama l'API addBreak. Sono necessari almeno due parametri: un espanso incorporato Break e un array di BreakClip. Se impostata su true, è inclusa una terza proprietà facoltativa per forzare l'invio delle modifiche ai mittenti connessi tramite una trasmissione MediaStatus. Quando aggiungi interruzioni e clip di interruzione, gli ID corrispondenti devono essere univoci. Questi annunci possono essere aggiunti solo dopo aver creato il player. L'SDK Web Receiver attiva l'evento PLAYER_LOADING dopo la creazione del player. Guarda l'esempio di seguito che mostra l'utilizzo in un gestore di eventi che risponde alle modifiche nei metadati ID3 di uno stream e crea oggetti Break e BreakClip per inserirli nella sequenza temporale.

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

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

Rimozione di annunci dinamici

Per rimuovere le interruzioni dinamiche, l'applicazione deve chiamare removeBreakById durante la riproduzione. La funzione acquisisce un identificatore stringa dell'interruzione da rimuovere dalla sequenza temporale. L'elemento breakId specificato deve indirizzare a un'interruzione pubblicitaria incorporata espansa. Se viene rilevato qualsiasi altro tipo di interruzione pubblicitaria, l'interruzione rimarrà nella sequenza temporale. Nell'esempio riportato di seguito viene rimossa un'interruzione.

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

breakManager.removeBreakById('break_midroll_embedded_expanded');

Comportamento delle interruzioni

L'SDK definisce un comportamento predefinito per il momento in cui il player entra ed esce da un'interruzione e offre un modo per personalizzarlo ulteriormente utilizzando alcune delle API fornite in BreakManager.

Comportamento predefinito dell'interruzione

Quando un Break viene inserito durante la riproduzione normale o cercando su un Break, l'SDK valuterà se l'utente l'ha già visualizzato controllando la proprietà isWatched. Quando viene creata, il valore predefinito di un'interruzione per questa proprietà è false. Se la proprietà è true, l'interruzione non verrà riprodotta quando viene inserita e continua la riproduzione del contenuto principale. Se la proprietà è false, verrà riprodotta l'interruzione quando viene inserita.

Nota: per le interruzioni pubblicitarie nella sequenza temporale incorporata, l'SDK cercherà per tutta la durata di un'interruzione guardata dall'utente per riprendere la riproduzione dei contenuti principali.

Quando cerchi interruzioni passate, l'implementazione predefinita ottiene tutti gli elementi Break il cui position si trova tra i valori seekFrom e seekTo dell'operazione di ricerca. In questo elenco di interruzioni, l'SDK riprodurrà il tag Break il cui position è più vicino al valore seekTo e la cui proprietà isWatched è impostata su false. La proprietà isWatched dell'interruzione verrà quindi impostata su true e il player avvierà la riproduzione delle clip di interruzione. Una volta guardata l'interruzione, la riproduzione dei contenuti principali riprenderà dalla posizione seekTo. In assenza di tale interruzione, non verrà riprodotta alcuna interruzione e la riproduzione dei contenuti principali riprenderà nella posizione seekTo.

Durante la riproduzione delle interruzioni, l'SDK trasmetterà tutti gli aggiornamenti pertinenti alle applicazioni del mittente collegate in MediaStatus. Queste applicazioni utilizzeranno le trasmissioni per aggiornare la propria UI per gli annunci leggendo la proprietà breakStatus. Questa proprietà viene definita solo durante la riproduzione delle interruzioni.

Nota: le applicazioni del destinatario possono iscriversi agli eventi PlayerManager MEDIA_STATUS per monitorare le modifiche in MediaStatus.

Le applicazioni ricevitore possono anche eseguire query direttamente sulle informazioni relative alla posizione della testina di riproduzione rispetto all'ora corrente dell'BreakClip mostrato chiamando PlayerManager getBreakClipCurrentTimeSec. Analogamente, le applicazioni possono eseguire query sulla durata dell'attuale BreakClip chiamando getBreakClipDurationSec.

Comportamento personalizzato dell'interruzione

Il comportamento predefinito per le interruzioni e i clip di interruzione può essere modificato utilizzando i metodi setBreakClipLoadInterceptor e setBreakSeekInterceptor forniti in BreakManager.

Nota: se esegui un'operazione di ricerca dopo il completamento di un'interruzione, assicurati che il valore playerState dell'oggetto MediaStatus sia stato modificato in PLAYING prima di eseguire l'operazione di ricerca.

Intercettore ricerca interruzione

L'intercettatore della ricerca di interruzione consente all'app di controllare il comportamento della ricerca delle interruzioni pubblicitarie. La funzione viene attivata quando viene richiesta un'operazione di ricerca che cerca in avanti o indietro in una o più interruzioni. Quando viene chiamato, BreakSeekData viene passato come parametro alla funzione di callback. L'oggetto BreakSeekData contiene un array di oggetti Break la cui proprietà position è impostata su un numero compreso tra il tempo attuale della testina di riproduzione definito come seekFrom e il tempo di destinazione della ricerca seekTo.

Questo intercettore consente di modificare gli oggetti Break nelle rispettive interruzioni. Una volta implementato, l'intercettatore della ricerca di interruzione deve specificare quali interruzioni pubblicitarie riprodurre restituendo un oggetto BreakSeekData modificato facoltativamente. Il player continuerà a riprodurre tutte le interruzioni incluse nel valore restituito. Se dall'intercettatore della ricerca di interruzione viene restituito un valore null o nulla, l'interruzione viene saltata.

Nota: l'impostazione dell'intercettatore della ricerca di interruzione sostituisce il comportamento predefinito. Sono incluse funzionalità come il salto delle interruzioni già guardate. Per personalizzare il comportamento della ricerca di interruzione e non riprodurre le interruzioni osservate, l'applicazione dovrà specificare questa logica nell'intercettatore della ricerca di interruzione controllando la proprietà isWatched di un Break. L'SDK gestirà l'impostazione della proprietà isWatched quando viene inserita un'interruzione, a prescindere dall'utilizzo da parte dell'intercettatore dell'interruzione di ricerca.

Nell'esempio riportato di seguito puoi vedere una semplice implementazione dell'intercettatore che sostituisce il comportamento predefinito in modo da controllare tutte le interruzioni pubblicitarie cercate, ad eccezione delle interruzioni già guardate.

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

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

Intercettore caricamento clip

Utilizzando l'intercettatore del caricamento del clip di interruzione, è possibile modificare un oggetto BreakClip prima che inizi la riproduzione.

L'intercettatore del caricamento del clip di interruzione viene chiamato solo per le interruzioni della sequenza temporale unite e può essere impostato utilizzando setBreakClipLoadInterceptor. Prima di inserire un Break, questo intercettore viene chiamato una volta per ogni individuo BreakClip definito nell'interruzione. L'SDK passa l'oggetto BreakClip originale come parametro della funzione di callback. L'applicazione può quindi modificare questo BreakClip e restituirlo in modo che l'SDK possa recuperare e visualizzare il clip di interruzione con la configurazione aggiornata. Se non viene restituito alcun valore o null, il clip di interruzione viene saltato.

Nota: se c'è un'interruzione pre-roll, l'intercettore del caricamento del clip di interruzione viene chiamato per l'interruzione pre-roll non appena inizia la riproduzione. Subito dopo il termine dell'interruzione pre-roll, viene richiamato l'intercettatore del caricamento del clip di interruzione per l'interruzione successiva, se esistente.

Di seguito è riportato un esempio che modifica il contentUrl dei clip di interruzione con una chiamata di funzione di utilità getUrlFromClipId, in cui id di BreakClip è mappato a un URL.

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

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

Mancata visualizzazione degli annunci

L'SDK Web Ricevir fornisce API per saltare le interruzioni pubblicitarie e singoli clip di interruzione pubblicitaria all'interno di un'interruzione pubblicitaria. L'SDK consente inoltre agli utenti di saltare i clip di interruzione interagendo con le applicazioni del mittente o con i dispositivi smart display.

Clip di interruzione ignorabili dell'utente

L'impostazione dei clip di interruzione come ignorabili consente agli utenti di interagire con le applicazioni dei mittenti connessi e i dispositivi smart display per saltare il resto di un clip di interruzione attualmente in riproduzione. Se imposti la proprietà whenSkippable su un numero non negativo di secondi, questa funzionalità viene attivata per l'oggetto BreakClip. Il player considera ignorabile il clip di interruzione dopo il numero di secondi specificato. Se questo valore viene impostato su 0, gli utenti possono saltare immediatamente il clip di interruzione.

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

Queste informazioni possono essere impostate nella richiesta di caricamento originale del mittente o nell'app del destinatario. Se viene ignorato, un clip di interruzione in un'interruzione pubblicitaria della sequenza temporale unita interromperà la riproduzione del clip di interruzione corrente. Il player caricherà il clip di interruzione successivo, se presente, oppure i contenuti principali. Se viene ignorato, un clip di interruzione in un'interruzione pubblicitaria di sequenza temporale incorporata cercherà fino alla fine del clip dell'interruzione e continuerà la riproduzione dello stream a quel punto.

Nota: oltre a implementare lo snippet riportato sopra, le applicazioni Web Sender devono aggiungere request logic per consentire a un utente di saltare un annuncio. Questa funzionalità non è necessaria sulle piattaforme per mittenti di dispositivi mobili, in quanto la funzionalità è fornita dall'SDK.

Ignorare gli annunci in modo programmatico

Gli annunci possono anche essere ignorati automaticamente senza alcuna interazione da parte dell'utente.

Per saltare un'intera pausa dalla riproduzione, un'applicazione deve impostare la proprietà isWatched di Break su true. Puoi farlo in qualsiasi momento durante la sequenza di caricamento o la riproduzione dei contenuti. La proprietà isWatched viene valutata dal giocatore quando il position di un'interruzione viene soddisfatto nell'ora attuale dei contenuti principali. A quel punto, sarà il player a decidere se inserire o meno un'interruzione. Guarda l'esempio riportato di seguito, che riproduce tutte le interruzioni e modifica il valore durante il caricamento del player.

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

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

Per saltare un clip di interruzione specifico in modo programmatico, è necessario utilizzare l'intercettore del caricamento del clip di interruzione. Se restituisci null o non restituisci un valore nella funzione di callback, il clip in quella interruzione verrà ignorato.

Nota: l'intercettatore del caricamento del clip di interruzione viene chiamato solo per le interruzioni della sequenza temporale unita. Se vuoi saltare le interruzioni in una sequenza temporale incorporata, esamina la rimozione degli annunci dinamici.

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

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});