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.
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:
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();
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)
};
}
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.
/**
* @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();
Comportamento delle interruzioni
Comportamento predefinito per le interruzioni
- 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. - Se un utente scorra oltre una o più interruzioni senza guardarle, viene riprodotta l'ultima interruzione non riprodotta tra le posizioni
seekFrom
eseekTo
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
.
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. SesetBreakSeekInterceptor
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
}];
}
Annunci con salto automatico
Gli annunci possono essere saltati automaticamente senza interazione da parte dell'utente. Esistono due modi per saltare gli annunci:
- 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;
}
}
});
- È possibile ignorare un elemento
BreakClip
restituisce un valore null nella funzione di callbacksetBreakClipLoadInterceptor
.playerManager.getBreakManager().setBreakClipLoadInterceptor(breakClip => {
return null;
});