SDK IMA DAI per Roku

    1. ima
    2. ima.AdBreakInfo
    3. ima.AdEvent
    4. ima.AdInfo
    5. ima.Companion
    6. ima.CuePoint
    7. ima.Error
    8. ima.ErrorEvent
    9. ima.Player
    10. ima.StreamFormat
    11. ima.StreamInfo
    12. ima.StreamManager
    13. ima.StreamRequest
    14. ima.StreamType
    15. ima.WrapperInfo

Class ima

Metodi

Funzioni globali che controllano l'SDK IMA.

disableLogging()

Disattiva il logging dell'SDK. La registrazione sarà attiva per impostazione predefinita.

getStreamManager()

Restituisce un gestore dello stream, se disponibile. Se lo stream manager non è ancora disponibile, viene restituito il valore Non valido. Se si è verificato un errore durante la creazione del gestore dello stream, viene restituito un oggetto errore.

Restituisce object: l'oggetto stream manager o errore.

initSdk(settings)

Inizializza l'SDK.

Parametro Tipo Descrizione
settings object

Oggetto facoltativo delle impostazioni IMA.

requestStream(streamRequest)

Avvia una richiesta di stream asincrona. Il controllo torna immediatamente al player dopo aver chiamato questo metodo.

Restituisce object: un errore o non valido se non si verificano errori

Parametro Tipo Descrizione
streamRequest object

Torna all'inizio

Classe ima.AdBreakInfo

Campi

Metodi

Contiene informazioni su un'interruzione pubblicitaria. Passato ai callback evento dall'SDK.

Proprietà

Nome Tipo Descrizione
adPosition

L'indice dell'annuncio nell'interruzione pubblicitaria. L'indice è 1 per gli annunci autonomi.

duration

La durata massima dell'interruzione in secondi o -1 se sconosciuta.

podIndex

Per i live streaming, restituisce l'ID interruzione come indice del pod o 0 per un preroll. I post-roll non sono disponibili nei live streaming. Il valore predefinito è -2. Per i video on demand (VOD), restituisce l'indice del pod di annunci. Per un pod preroll, restituisce 0. Per gli annunci mid-roll, restituisce 1, 2, ..., n. Per un pod post-roll, restituisce n+1…n+x. Il valore predefinito è 0 se l'annuncio non fa parte di un pod o se il pod non fa parte di una playlist.

timeOffset

La posizione del pod nei contenuti in secondi. Il pre-roll restituisce 0, il post-roll restituisce -1 e i mid-roll restituiscono l'ora pianificata del pod.

totalAds

Il numero totale di annunci contenuti in questa interruzione pubblicitaria. Il valore è 1 per gli annunci autonomi.

createAdBreakInfo()


Restituisce ima.AdBreakInfo:

Torna all'inizio

Classi ima.AdEvent

Campi

Eventi attivati dall'amministratore degli annunci.

Proprietà

Nome Tipo Descrizione
AD_PERIOD_ENDED

Viene attivato ogni volta che lo stream passa dalla pubblicità o dalla scheda ai contenuti. Viene attivato anche quando un annuncio viene riprodotto una seconda volta o quando viene eseguito il passaggio in un annuncio.

AD_PERIOD_STARTED

Viene attivato ogni volta che lo stream passa dai contenuti alla pubblicità o allo slate. Viene attivato anche quando un annuncio viene riprodotto una seconda volta o quando viene eseguito il passaggio in un annuncio.

COMPLETE

Attivato quando termina la riproduzione dell'annuncio.

ERROR

Viene attivato quando si verifica un errore.

FIRST_QUARTILE

Attivato quando il cursore di riproduzione dell'annuncio supera il primo quartile.

ICON_FALLBACK_IMAGE_CLOSED

Viene attivato quando l'utente chiude la finestra di dialogo dell'immagine di riserva dell'icona.

ICON_FALLBACK_IMAGE_SHOWN

Viene attivato quando viene visualizzata l'immagine di riserva dell'icona.

MIDPOINT

Attivato quando la testina di riproduzione dell'annuncio supera il punto intermedio.

PROGRESS

Viene attivato quando viene aggiornato l'avanzamento di un annuncio.

SKIPPABLE_STATE_CHANGED

Viene attivato quando cambia lo stato di ignorabilità di un annuncio.

SKIPPED

Attivato quando un annuncio viene ignorato.

START

Attivato quando inizia la riproduzione di un annuncio.

THIRD_QUARTILE

Attivato quando la barra di riproduzione dell'annuncio supera il terzo quartile.

Torna all'inizio

Classe ima.AdInfo

Campi

Metodi

Contiene informazioni su un annuncio. Passato ai callback evento dall'SDK.

Proprietà

Nome Tipo Descrizione
adBreakInfo

Informazioni relative all'intera interruzione in cui si trova l'annuncio.

adDescription

La descrizione dell'annuncio.

adId

L'ID dell'annuncio o una stringa vuota se sconosciuto.

adSystem

Il sistema pubblicitario che fornisce la creatività.

adTitle

Il titolo dell'annuncio.

advertiserName

Il nome dell'inserzionista come definito dalla parte che pubblica.

companions

Gli annunci companion specificati nella risposta VAST.

creativeAdId

Il codice ISCI (Industry Standard Commercial Identifier) di un annuncio. Si tratta dell'ID annuncio della creatività selezionata nella risposta VAST.

creativeId

L'ID della creatività selezionata per l'annuncio.

currentTime

L'ora corrente all'interno di un annuncio in secondi o -1 se sconosciuta.

dealId

Restituisce il primo ID deal presente nella catena di wrapper per l'annuncio corrente, partendo dall'alto.

duration

La durata di questo singolo annuncio in secondi o -1 se sconosciuta.

skipOffset

Il tempo necessario per rendere l'annuncio ignorabile o -1 se sconosciuto.

universalAdIDRegistry

Una stringa utilizzata per identificare l'URL del sito web del registry in cui è catalogato l'ID annuncio universale della creatività selezionata.

universalAdIDValue

L'ID annuncio universale della creatività selezionata per l'annuncio.

wrappers

Un array di ima.WrapperInfo con le informazioni sul wrapper per questo annuncio. L'ordine sarà dal wrapper esterno a quello interno.

createAdInfo()


Restituisce ima.AdInfo:

Torna all'inizio

Classi ima.Companion

Campi

Metodi

Contiene informazioni sugli annunci companion di un annuncio.

Proprietà

Nome Tipo Descrizione
apiFramework

L'API necessaria per eseguire questo annuncio o Non valido se non disponibile.

creativeType

Rappresenta il tipo di creatività, in genere un tipo MIME.

height

L'altezza del compagno in pixel. 0 se non disponibile.

trackingEvents

Una mappa di eventi di monitoraggio in cui la chiave è l'evento e il valore è un elenco di URL da eseguire in ping per quell'evento.

url

L'URL della risorsa statica di questo companion.

width

La larghezza del compagno in pixel. 0 se non disponibile.

createCompanion()


Restituisce ima.Companion:

Torna all'inizio

Classi ima.CuePoint

Campi

Metodi

Contiene informazioni su un cue point.

Proprietà

Nome Tipo Descrizione
end

La data e l'ora di fine di un cue point in secondi. Corrisponde a un'interruzione pubblicitaria.

hasPlayed

Un valore booleano che indica che il cue point è già stato riprodotto.

start

L'ora di inizio di un cue point in secondi. Corrisponde a un'interruzione pubblicitaria.

createCuePoint()


Restituisce ima.CuePoint:

Torna all'inizio

Classi ima.Error

Campi

Metodi

Oggetto passato al gestore degli errori in caso di errore.

Proprietà

Nome Tipo Descrizione
id

L'ID dell'errore. Consulta la costante ErrorEvent per un elenco dei codici di errore.

info

Informazioni aggiuntive sull'errore.

type

Imposta sempre su error per indicare il tipo di questo oggetto.

createError()


Restituisce ima.Error:

Torna all'inizio

Class ima.ErrorEvent

Campi

Tutti gli errori che l'SDK potrebbe restituire.

Proprietà

Nome Tipo Descrizione
BAD_STREAM_REQUEST

La richiesta di stream non è stata compilata correttamente.

COULD_NOT_LOAD_STREAM

Impossibile caricare lo stream.

ERROR

Un errore sconosciuto.

INVALID_RESPONSE

La risposta del server non è valida.

STREAM_API_KEY_NOT_VALID

La chiave API fornita non è stata accettata dal server.

Torna all'inizio

Classe ima.Player

Metodi

adBreakEnded(adBreakInfo)

(Facoltativo) Viene chiamato al termine di un'interruzione pubblicitaria.

Parametro Tipo Descrizione
adBreakInfo ima.AdBreakInfo

Contiene informazioni sull'interruzione pubblicitaria.

adBreakStarted(adBreakInfo)

(Facoltativo) Viene chiamato quando inizia un'interruzione pubblicitaria.

Parametro Tipo Descrizione
adBreakInfo ima.AdBreakInfo

Contiene informazioni sull'interruzione pubblicitaria.

allVideoComplete()

(Facoltativo) Viene chiamato quando il video è completo.

createPlayer()

Crea un oggetto IMA Player vuoto. Devi implementare la funzione loadUrl per riprodurre gli annunci. Le altre funzioni sono facoltative.

Restituisce ima.Player:

loadUrl(streamInfo)

Viene chiamato quando il player deve iniziare a riprodurre un URL. Devi implementare questo metodo per caricare lo stream.

Parametro Tipo Descrizione
streamInfo ima.StreamInfo

Contiene le informazioni necessarie per riprodurre i contenuti.

Torna all'inizio

Classe ima.StreamFormat

Campi

Definisce il formato dello stream.

Proprietà

Nome Tipo Descrizione
DASH

HLS

Torna all'inizio

Classe ima.StreamInfo

Campi

Metodi

Informazioni sullo stream trasmesse dall'SDK al player.

Proprietà

Nome Tipo Descrizione
format

Il formato del video: hls o dash. Definito in ima.StreamFormat.

manifest

URL dello stream.

streamId

Un ID univoco per lo stream.

streamType

Il tipo di video: dal vivo o on demand. Definito in ima.StreamType.

subtitles

Sottotitoli, se disponibili. Non valido in caso contrario.

createStreamInfo()


Restituisce ima.StreamInfo:

Torna all'inizio

Classe ima.StreamManager

Metodi

Oggetto per la gestione della riproduzione dello stream.

addEventListener(event, callback)

Aggiunge un ascoltatore per l'evento specificato. Consulta la costante AdEvents per gli eventi supportati.

Parametro Tipo Descrizione
event string

callback function

createStreamManager(streamRequest, streamInitResponse)


Restituisce ima.StreamManager:

Parametro Tipo Descrizione
streamRequest ima.StreamRequest

streamInitResponse ima.StreamInitResponse

enableInteractiveAds()

Non supportato. Passa invece i dati dall'annuncio companion direttamente al RAF. Ora non è più necessario.

getContentTime(streamTime)

Restituisce un valore in millisecondi per uno stream VOD, che rappresenta il tempo nei contenuti senza annunci. Per maggiori dettagli, consulta le Domande frequenti. Per ottenere l'ora dei contenuti per l'ora corrente dello stream, passa -1.

Restituisce Integer: l'ora dei contenuti corrispondente all'ora dello stream specificata.

Parametro Tipo Descrizione
streamTime Integer

L'ora nello stream.

getCuePoints()

Restituisce tutti i cue point corrispondenti a tutte le interruzioni pubblicitarie. Questo vale solo per i contenuti video on demand in cui tutte le interruzioni pubblicitarie sono note in anticipo. Tutti i tempi rappresentano il tempo dello stream in secondi. Per gli stream dell'API Cloud Stitching, la proprietà hasPlayed di ogni ima.CuePoint è sempre false.

Restituisce Object: un array con tutti i cue point.

getPreviousCuePoint(time)

Restituisce il cue point precedente a questo momento. Il cue point indica un'interruzione pubblicitaria. Tutti i tempi rappresentano il tempo dello stream in secondi.

Restituisce ima.CuePoint: un oggetto con start, end e hasPlayed. Restituisce non valido se non è disponibile alcun cue point.

Parametro Tipo Descrizione
time Float

L'ora da cercare, -1 indica l'ora corrente e restituisce Invalid per tutti gli altri stream.

getStreamTime(contentTime)

Recupera il tempo dello stream da un tempo dei contenuti per VOD in millisecondi. Per maggiori dettagli, consulta le Domande frequenti.

Restituisce Integer: l'ora dello stream corrispondente all'ora dei contenuti specificata.

Parametro Tipo Descrizione
contentTime Integer

La data e l'ora dei contenuti.

loadThirdPartyStream(streamManifest, streamSubtitle)

Carica i metadati dell'annuncio e chiama la funzione loadUrl con i dati streamManifestUrl e streamSubtitle forniti. Questa funzione funziona solo quando il tipo di richiesta di streaming è ima.StreamType.POD_VOD.

Parametro Tipo Descrizione
streamManifest string

L'URL manifest dello stream con gli annunci uniti.

streamSubtitle ifArray>|Invalid

I sottotitoli associati allo stream o Invalid se non sono presenti.

onMessage(msg)

Gestisce tutti i messaggi provenienti dall'oggetto Video. Deve essere chiamato per ogni messaggio ricevuto su roMessagePort.

Parametro Tipo Descrizione
msg object

Il messaggio dalla porta roVideo.

replaceAdTagParameters(adTagParameters)

Sostituisce tutti i parametri dei tag annuncio da utilizzare per le richieste di annunci imminenti per un live streaming. Tieni presente che questa chiamata non ha alcun effetto sugli stream VOD.

Parametro Tipo Descrizione
adTagParameters string

I nuovi parametri del tag annuncio.

start()

Avvia la riproduzione dello stream.

Torna all'inizio

Classe ima.StreamRequest

Campi

Metodi

Utilizzato per specificare le proprietà della richiesta di streaming.

Proprietà

Nome Tipo Descrizione
adTagParameters

(Facoltativo) Puoi sostituire un insieme limitato di parametri dei tag annuncio nella richiesta di stream. Per ulteriori informazioni, consulta l'articolo Fornire parametri di targeting alla riproduzione in streaming. Puoi anche utilizzare i parametri dai-ot e dai-ov per la preferenza della variante di stream. Per saperne di più, consulta la sezione Sostituire i parametri delle varianti per la riproduzione in streaming.

adUiNode

Un nodo del grafo della scena in cui viene visualizzata l'interfaccia utente dell'annuncio. IMA inserisce elementi come Perché questo annuncio e i pulsanti Salta in questo elemento durante gli annunci. L'elemento deve essere sovrapposto all'intero elemento video.

apiKey

(Facoltativo) Queste chiavi possono essere utilizzate per autenticare le richieste di streaming. Le chiavi di autenticazione DAI devono essere configurate nell'interfaccia utente di DFP.

assetKey

Obbligatorio per i live streaming. Viene utilizzato per determinare quale stream deve essere riprodotto. La chiave asset della richiesta del live streaming è un identificatore che puoi trovare nell'interfaccia utente di DFP.

authToken

Il token di autorizzazione della richiesta di stream. Utilizzato al posto della chiave API per un'autorizzazione dei contenuti più rigorosa. Il publisher può controllare le autorizzazioni dei singoli stream di contenuti in base a questo token.

contentSourceId

Obbligatorio per gli stream on demand. Il valore cmsid proviene dalla fonte di contenuti video DFP nell'interfaccia utente di DFP.

customAssetKey

La chiave dell'asset personalizzato viene utilizzata per determinare quale stream deve essere riprodotto. Le chiavi asset personalizzate sono necessarie per le richieste di streaming del servizio pod.

format

Il formato dello stream. Il valore predefinito è ima.StreamFormat.HLS.

networkCode

Il codice di rete del publisher che effettua la richiesta di streaming. I codici di rete sono obbligatori per le richieste di stream di pubblicazione pod effettuate con createPodLiveStreamRequest o createPodVodStreamRequest. Questi codici sono obbligatori anche per le richieste di stream di Stitching Cloud effettuate con createVideoStitcherLiveStreamRequest, createVideoStitcherVodStreamRequest o createVideoStitcherVodStreamRequestWithVodConfig. Questi codici sono facoltativi e consigliati per le richieste di stream con servizio completo effettuate con createLiveStreamRequest o createVodStreamRequest. L'aggiunta del codice di rete consente di applicare le impostazioni selezionate nell'interfaccia utente di Ad Manager, ad esempio l'attivazione degli annunci programmatici con limitazioni. Per il caricamento dei pod e l'unione in cloud, l'aggiunta del codice di rete consente di individuare e riprodurre lo stream. Per trovare il codice di rete, consulta questo articolo.

player

Un'implementazione dell'interfaccia del player.

ppid

Deprecato. Utilizza adTagParameters. (Facoltativo) Un identificatore fornito dal publisher per i segmenti di pubblico DFP.

streamActivityMonitorId

L'ID da utilizzare per eseguire il debug dello stream con il monitoraggio attività di streaming. Questo viene utilizzato per fornire un modo pratico per consentire ai publisher di trovare un log dello stream nello strumento di monitoraggio delle attività di streaming.

videoId

Obbligatorio per gli stream on demand. Identificatore dell'origine di contenuti video.

videoObject

L'oggetto video (ad esempio Video roSGNode) responsabile della riproduzione video nell'app client. Questo oggetto verrà sottoposto a polling per vari dati da utilizzare per impostare correttamente la temporizzazione degli eventi ID3 HLS dal vivo.

videoStitcherSessionOptions

Le opzioni di sessione vengono utilizzate per impostare parametri specifici per gli autori di montaggi video per le richieste di stream di VideoStitcher.

createLiveStreamRequest(assetKey, apiKey, networkCode)

Inizializza le proprietà obbligatorie di un StreamRequestlive streaming. L'utilizzo di questa API comporta l'ignoramento di eventuali altre proprietà specifiche di StreamType. Se uno o più parametri obbligatori sono stringhe vuote, viene generato un log degli errori e l'API restituisce un StreamRequest generico, senza proprietà ignorate.

Restituisce ima.StreamRequest: oggetto ima.StreamRequest con proprietà Live obbligatorie.

Parametro Tipo Descrizione
assetKey string

apiKey string

Parametro assegnato alla proprietà ima.StreamRequest.apiKey ima.StreamRequest. Se non esiste una chiave API, passa una stringa vuota.

networkCode string

Codice di rete del publisher che effettua la richiesta di streaming. L'inclusione del codice di rete è facoltativa, ma consigliata.

createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)

Inizializza le proprietà obbligatorie di un pod live ima.StreamRequest. L'utilizzo di questa API comporta l'ignoramento di qualsiasi altra proprietà specifica per ima.StreamType. Se uno o più parametri obbligatori sono stringhe vuote, viene generato un log degli errori e l'API restituisce un StreamRequest generico, senza proprietà ignorate.

Restituisce StreamRequest: oggetto ima.StreamRequest con le proprietà obbligatorie di PodLive.

Parametro Tipo Descrizione
customAssetKey string

networkCode string

apiKey string

Parametro facoltativo assegnato alla proprietà ima.StreamRequest.apiKey del valore ima.StreamRequest restituito. Il valore predefinito è una stringa vuota.

createPodVodStreamRequest(networkCode)

Inizializza le proprietà richieste di un ima.StreamRequest per registrare uno streaming VOD quando si utilizza la pubblicazione di pod DAI con un'applicazione di stitching video di terze parti. Questa funzione imposta il tipo di richiesta su ima.StreamType.POD_VOD e convalida tutte le proprietà obbligatorie per i dati mancanti. Le convalide non riuscite registreranno un errore nella console di debug.

Restituisce StreamRequest: un oggetto ima.StreamRequest. Se tutte le proprietà obbligatorie sono specificate, il tipo di richiesta viene impostato su ima.StreamType.POD_VOD.

Parametro Tipo Descrizione
networkCode string

il codice di rete Google Ad Manager

createStreamRequest()


Restituisce ima.StreamRequest: un oggetto ima.StreamRequest vuoto.

createVideoStitcherLiveStreamRequest(customAssetKey, networkCode, liveConfigId, region, projectNumber, oAuthToken)

Inizializza le proprietà obbligatorie di un StreamRequestVideo Stitcher Live. L'utilizzo di questa API comporta l'ignoramento di qualsiasi altra proprietà specifica per StreamType. Se uno o più parametri obbligatori sono stringhe vuote, viene generato un log degli errori e l'API restituisce un StreamRequest generico, senza proprietà ignorate.

Restituisce ima.StreamRequest: oggetto ima.StreamRequest con le proprietà VideoStitcherLive obbligatorie.

Parametro Tipo Descrizione
customAssetKey string

networkCode string

liveConfigId string

region string

projectNumber string

oAuthToken string

createVideoStitcherVodStreamRequest(adTagUrl, networkCode, contentSourceUrl, region, projectNumber, oAuthToken)

Inizializza le proprietà obbligatorie di una VOD Video StitcherStreamRequest. L'utilizzo di questa API comporta l'ignoramento di qualsiasi altra proprietà specifica per StreamType. Se uno o più parametri obbligatori sono stringhe vuote, viene generato un log degli errori e l'API restituisce un StreamRequest generico, senza proprietà ignorate.

Restituisce ima.StreamRequest: oggetto ima.StreamRequest con le proprietà VideoStitcherVod obbligatorie.

Parametro Tipo Descrizione
adTagUrl string

networkCode string

contentSourceUrl string

region string

projectNumber string

oAuthToken string

createVideoStitcherVodStreamRequestWithVodConfig(vodConfigId, networkCode, region, projectNumber, oAuthToken)

Inizializza le proprietà richieste di una VOD Video Stitcher StreamRequest utilizzando vodConfigId creato da Video Stitcher cloud. L'utilizzo di questa API comporta l'ignoramento di altre proprietà specifiche di StreamType. Se uno o più parametri obbligatori sono stringhe vuote, viene generato un log degli errori e l'API restituisce un StreamRequest generico, senza proprietà ignorate.

Restituisce ima.StreamRequest: oggetto ima.StreamRequest con le proprietà VideoStitcherVod obbligatorie.

Parametro Tipo Descrizione
vodConfigId string

networkCode string

region string

projectNumber string

oAuthToken string

createVodStreamRequest(contentSourceId, videoId, apiKey, networkCode)

Inizializza le proprietà obbligatorie di un VOD ima.StreamRequest. L'utilizzo di questa API comporta l'ignoramento di eventuali altre proprietà specifiche di ima.StreamType. Se uno o più parametri obbligatori sono stringhe vuote, viene generato un log degli errori e l'API restituisce un StreamRequest generico, senza proprietà ignorate.

Restituisce ima.StreamRequest: oggetto ima.StreamRequest con le proprietà VOD obbligatorie.

Parametro Tipo Descrizione
contentSourceId string

videoId string

apiKey string

Parametro assegnato alla proprietà ima.StreamRequest.apiKey ima.StreamRequest. Se non esiste una chiave API, passa una stringa vuota.

networkCode string

Codice di rete del publisher che effettua la richiesta di streaming. L'inclusione del codice di rete è facoltativa, ma consigliata.

Torna all'inizio

Class ima.StreamType

Campi

Definisce il tipo di stream che il player deve riprodurre. I preroll e i VOD devono essere riprodotti dall'inizio dello stream.

Proprietà

Nome Tipo Descrizione
LIVE

Il video è pubblico.

VOD

Il video è on demand.

Torna all'inizio

Classe ima.WrapperInfo

Campi

Metodi

Contiene informazioni su un wrapper.

Proprietà

Nome Tipo Descrizione
adId

L'ID dell'annuncio o una stringa vuota se sconosciuto.

adSystem

Il nome dichiarato del sistema pubblicitario o una stringa vuota se sconosciuto.

creativeAdId

L'ID annuncio nella creatività o una stringa vuota se sconosciuto.

creativeId

L'ID della creatività o una stringa vuota se non è noto.

dealId

L'ID deal o una stringa vuota se sconosciuto.

createWrapperInfo()


Restituisce ima.WrapperInfo:

Torna all'inizio