Interruzioni pubblicitarie

Panoramica

L'SDK Web receiver prevede il supporto nativo per le interruzioni pubblicitarie e gli annunci companion all'interno di un determinato stream multimediale. Fornisce API per impostare la posizione dell'annuncio, l'origine e il comportamento delle interruzioni pubblicitarie e i relativi clip di interruzione associati. In questa guida, un Break indica un intervallo di riproduzione contenente uno o più annunci o bumper e ogni annuncio o bumper viene definito BreakClip. Queste interruzioni sono associate ai contenuti multimediali che vengono caricati o riprodotti.

Tipi di annuncio

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

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

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

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_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"
  }
]

// 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;

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

// 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 del player

Durante la creazione di un'istanza di player, l'SDK Web receiver seleziona un tipo di sequenza temporale da supportano la riproduzione di annunci durante la riproduzione dei contenuti. Ogni sequenza temporale abilita determinati annunci tipi di interruzione da aggiungere. Il tipo di sequenza temporale è determinato tipi di annunci presenti durante il tempo di caricamento nell' MediaInformation: del LoadRequestData. Se sono presenti interruzioni pubblicitarie incorporate, viene selezionata la sequenza temporale embedded. Se sono presenti interruzioni pubblicitarie integrate dal client; è selezionata la sequenza temporale stitched. Nel caso in cui non siano presenti annunci, l'SDK utilizza per impostazione predefinita l'embedded sequenza temporale. Una volta selezionata, la sequenza temporale non può essere modificata per quella attuale elemento multimediale. La tabella riportata di seguito fornisce una descrizione dettagliata di ciascuna sequenza temporale.

Le immagini da 1 a 3 di seguito illustrano alcuni contenuti con tipi di annunci diversi e i relativi i rispettivi valori della sequenza temporale. I contenuti sono configurati con un'interruzione pre-roll contenente due clip di interruzione e interruzioni mid-roll e post-roll contenenti con una singola interruzione. Il tempo reale dall'inizio della riproduzione dei contenuti. il tempo multimediale dei contenuti principali e l'ora della pausa attualmente l'interruzione della riproduzione di un clip è allineata sotto ogni figura.

Interrompi posizionamento

L'SDK WebRicevir consente agli sviluppatori di specificare la posizione delle interruzioni pubblicitarie inserire impostando position proprietà di Break. Questo valore corrisponde al tempo multimediale del contenuto principale e può essere utilizzato per creare interruzioni pubblicitarie pre-roll, mid-roll e post-roll. Queste sono definite come segue:

Matrice interoperabilità

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

Eventi

Quando si verificano eventi di interruzione chiave, l'SDK Cast invia eventi di tipo BreaksEvent Un'app ricevente può abbonarsi utilizzando PlayerManager addEventListener tramite Google Cloud CLI o tramite l'API Compute Engine.

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

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

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 vengano specificati annunci nel LoadRequestData: prima della creazione del player. L'inserimento di annunci dinamici utilizza la classe BreakManager: addBreak API per inserire interruzioni nei contenuti già caricati. Ogni tipo di inserimento è compatibile con determinati tipi di annunci. Una compatibilità panoramica è fornita nella matrice di interoperabilità.

Inserimento di annunci statici

L'inserimento di annunci statici viene caratterizzato dall'aggiunta dei metadati dell'annuncio pertinenti prima alla creazione dei player. Queste informazioni vengono fornite nella MediaInformation di LoadRequestData. Ad esempio, può essere impostato nel set di dati richiesta di caricamento originale oppure può essere inserita dall'applicazione WebRicevitore che intercetta la richiesta LOAD. Una volta che LoadRequestData viene restituito SDK Web ricevitore per l'elaborazione, il player viene creato. Vedi di più su caricamento di contenuti multimediali. L'esempio di seguito mostra un annuncio con stitching manuale manuale che viene aggiunto alla richiesta LOAD intercettore.

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 i contenuti per riprodurre un video. Per farlo, devi ottenere un'istanza di BreakManager e chiamare il addBreak tramite Google Cloud CLI o tramite l'API Compute Engine. che richiede almeno due parametri, incorporato espanso Break e un array di BreakClip. È inclusa una terza proprietà facoltativa per forzare l'invio delle modifiche a mittenti connessi tramite una trasmissione MediaStatus se impostato su true. Quando aggiungendo interruzioni e clip di interruzione, gli ID corrispondenti devono essere univoci. Questi annunci può essere aggiunto solo dopo la creazione del player. Viene attivato l'SDK WebRicevir il PLAYER_LOADING una volta creato il player. Guarda l'esempio di seguito che mostra l'utilizzo in un gestore di eventi che risponda alle modifiche nei metadati ID3 di uno stream, 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 richiamare removeBreakById durante la riproduzione. La funzione acquisisce un identificatore di stringa dell'interruzione da rimosso dalla sequenza temporale. Il parametro breakId specificato deve puntare a un elemento incorporato interruzione pubblicitaria espansa. Se viene rilevato qualsiasi altro tipo di interruzione pubblicitaria, l'interruzione rimangono nella sequenza temporale. Di seguito è riportato l'esempio che rimuove 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 quando il player inserisce e lascia le interruzioni e offre un modo per personalizzarlo ulteriormente utilizzando alcune delle API fornite nel BreakManager

Comportamento predefinito per l'interruzione

Quando viene inserito un Break tramite la riproduzione normale o cercando sopra un Break, l'SDK valuterà se l'utente l'ha già visto controllando il isWatched proprietà. Quando viene creata, il valore predefinito di un'interruzione per questa proprietà è false. Se La proprietà è true, l'interruzione non verrà riprodotta se inserita e principale la riproduzione dei contenuti continuerà. Se la proprietà è false, l'interruzione sarà vengono riprodotti quando inseriti.

Quando cercano le pause, l'implementazione predefinita ottiene tutti i Break elementi il cui position si trova tra seekFrom: e seekTo e i relativi valori. In questo elenco di interruzioni, l'SDK riprodurrà l'elemento Break, il cui position è il 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 inizierà a riprodurre i suoi clip di interruzione. Dopo aver guardato la pausa, la riproduzione dei contenuti principali riprenderà dalla posizione seekTo. In caso contrario, l'interruzione esiste, non verrà riprodotta alcuna interruzione e riprenderanno i contenuti principali gioca nella posizione seekTo.

Durante la riproduzione, l'SDK trasmette tutti gli aggiornamenti pertinenti le applicazioni di mittenti MediaStatus Queste applicazioni utilizzeranno gli annunci per aggiornare l'interfaccia utente per gli annunci il breakStatus proprietà. Questa proprietà viene definita soltanto durante la riproduzione delle interruzioni.

Le applicazioni ricevitori possono anche interrogare direttamente le informazioni relative al posizione della testina di riproduzione rispetto all'ora corrente di BreakClip mostrato chiamando PlayerManager getBreakClipCurrentTimeSec Allo stesso modo, le applicazioni possono eseguire query sulla durata dell'attuale BreakClip mediante chiamata getBreakClipDurationSec

Comportamento dell'interruzione personalizzata

Il comportamento predefinito per le interruzioni e i clip di interruzione possono essere modificati setBreakClipLoadInterceptor: e setBreakSeekInterceptor metodi forniti in BreakManager.

Intercettore di ricerca interruzione

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

Questo intercettore consente agli oggetti Break nelle rispettive interruzioni di essere modificato. Se implementata, l'intercettatore di ricerca dell'interruzione deve specificare quale annuncio da riprodurre restituendo un oggetto BreakSeekData modificato facoltativamente. La il giocatore continuerà a giocare tutte le interruzioni incluse nel valore restituito. Se un valore di null o non viene restituito nulla dall'intercettatore di ricerca dell'interruzione, l'interruzione è saltato.

Guarda l'esempio riportato di seguito per una semplice implementazione dell'intercettore, sostituisce il comportamento predefinito per guardare tutte le interruzioni pubblicitarie cercate con il 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 di caricamento del clip di interruzione

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

L'intercettatore di carico del clip di interruzione è chiamato solo per interruzioni della sequenza temporale unite e possono essere impostati utilizzando setBreakClipLoadInterceptor Prima di inserire un valore Break, questo intercettore viene chiamato una volta per ogni individuo BreakClip definito in quell'interruzione. L'SDK trasmette i dati BreakClip come parametro della funzione callback. L'applicazione può quindi modificare questo BreakClip e restituirlo in modo che l'SDK possa recuperare e visualizzare l'interruzione con la configurazione aggiornata. Se null o non viene restituito nulla, l'interruzione viene saltato il clip.

Di seguito è riportato un esempio che modifica contentUrl dei clip di interruzione con una chiamata di funzione di utilità getUrlFromClipId, dove 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;
});

Salta annuncio

L'SDK WebRicevir fornisce API per saltare le interruzioni pubblicitarie e i singoli clip delle interruzioni durante un'interruzione pubblicitaria. L'SDK consente inoltre agli utenti di saltare facoltativamente i clip delle interruzioni interagendo con le applicazioni di invio o gli smart display.

Clip di interruzione ignorabili dell'utente

L'impostazione dei clip di interruzione come ignorabili consente agli utenti di interagire con il mittente connesso applicazioni e smart display in modo da saltare il resto è attualmente in riproduzione un clip di interruzione. L'impostazione del parametro whenSkippable con un numero non negativo di secondi abiliterà questa funzionalità per BreakClip oggetto. Il player considererà ignorabile il clip di interruzione una volta che è stato riprodotto il numero di secondi specificato. Se imposti questo valore su 0, consente agli utenti di saltare subito il clip dell'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 nel ricevitore. Se l'azione viene saltata, un clip di interruzione in un'interruzione pubblicitaria della sequenza temporale unita. interrompe la riproduzione del clip di interruzione corrente. Il player caricherà interrompi clip, se presente, o carica i contenuti principali. Se l'azione viene saltata, il clip di un'interruzione un'interruzione pubblicitaria nella sequenza temporale incorporata cercherà fino alla fine del clip dell'interruzione continua la riproduzione dello stream a quel punto.

Saltare 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 classe isWatched: di un valore da Break a true. Questa operazione può essere eseguita in qualsiasi momento durante il caricamento sequenza o contenuti. La proprietà isWatched viene valutata dalla player quando il valore position di una pausa viene soddisfatto nell'ora attuale dei contenuti principali. Alle ore in quel punto, sarà il giocatore a decidere se inserire o meno una pausa. Osserva l'esempio riportato di seguito che si ripete in tutte le interruzioni e modifica le 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 specifica in modo programmatico, utilizza il comando deve essere utilizzato l'intercettatore di caricamento del clip di interruzione. Di restituendo null o non restituendo un valore nella funzione di callback, il clip in l'interruzione verrà saltata.

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

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