Gli SDK IMA semplificano l'integrazione di annunci multimediali nei tuoi siti web e nelle tue app.
Gli SDK IMA possono richiedere annunci da qualsiasi ad server conforme a VAST e gestire la riproduzione degli annunci nelle tue app.
Con gli SDK IMA DAI, le app inviano una richiesta di stream per gli annunci e i contenuti video per i contenuti VOD o live. L'SDK restituisce quindi uno stream video combinato, in modo che tu non debba gestire il passaggio tra l'annuncio e il video dei contenuti all'interno della tua app.
Questa guida mostra come riprodurre uno stream di pubblicazione di pod DAI utilizzando l'SDK IMA DAI per CAF.
Prima di utilizzare questa guida, acquisisci familiarità con il protocollo Web Receiver di Chromecast Application Framework. Questa guida presuppone una conoscenza di base dei concetti relativi ai ricevitori CAF, come gli intercettatori di messaggi e gli oggetti mediaInformation, nonché una certa familiarità con l'utilizzo dello strumento Cast Command and Control per emulare un mittente CAF.
Per utilizzare la pubblicazione di pod DAI IMA, devi collaborare con un partner per la pubblicazione di pod e disporre di un account Ad Manager 360 Advanced. Se hai un account Ad Manager, contatta il tuo account manager per maggiori dettagli. Per informazioni su come registrarti ad Ad Manager, visita il Centro assistenza Ad Manager.
Per informazioni sull'integrazione con altre piattaforme o sull'utilizzo degli SDK IMA lato client, consulta SDK Interactive Media Ads.
Panoramica della pubblicazione di pod IMA DAI
L'implementazione della pubblicazione pod utilizzando l'SDK DAI IMA CAF prevede due componenti principali, illustrati in questa guida:
StreamRequest: un oggetto che definisce una richiesta di stream ai server pubblicitari di Google. Le richieste specificano un codice di rete, una chiave asset personalizzata e una chiave API facoltativa, oltre ad altri parametri facoltativi.StreamManager: un oggetto che gestisce la comunicazione tra lo stream video e l'SDK IMA DAI, ad esempio l'attivazione dei ping di monitoraggio e l'inoltro degli eventi di stream al publisher.
Prerequisiti
- Un account Cast Developer Console con dispositivi di test registrati.
- Un'app Web Receiver ospitata registrata con Cast Developer Console e che può essere modificata per ospitare il codice fornito da questa guida.
- Un'app mittente configurata per utilizzare l'app Web Receiver. Ai fini di questo esempio, utilizza lo strumento Cast Command and Control come mittente.
Configura gli oggetti MediaInfo del mittente
Innanzitutto, configura l'oggetto MediaInfo dell'app mittente in modo da includere i seguenti campi:
| Campo | Sommario | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
contentId
|
Un identificatore univoco per questo elemento multimediale.
CONTENT_ID |
||||||||||
contentUrl
|
Facoltativo. URL dello stream di backup da riprodurre se lo stream DAI non viene caricato.
BACKUP_STREAM_URL |
||||||||||
contentType
|
Facoltativo. Tipo MIME degli stream di backup dei contenuti. Obbligatorio solo per gli stream DASH.
CONTENT_STREAM_MIMETYPE |
||||||||||
streamType
|
La stringa letterale o la costante utilizzata per questo valore varia in base alla piattaforma del mittente. | ||||||||||
customData
|
Il campo customData contiene un archivio di coppie chiave-valore di campi obbligatori aggiuntivi. In questo esempio, contiene i parametri dello stream DAI. In un'app di produzione, potresti invece passare un identificatore che l'app ricevitore Cast utilizzerebbe per recuperare questi parametri con una richiesta lato server.
|
Ecco alcuni esempi di codice per aiutarti a iniziare:
Web
Per configurare questi valori in un mittente web Cast, crea prima un oggetto MediaInfo con i dati richiesti, quindi invia una richiesta di caricamento al ricevitore web.
// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "CONTENT_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.LIVE;
mediaInfo.customData = {
daiStreamType: "DAI_STREAM_TYPE",
networkCode: "NETWORK-CODE",
customAssetKey: "CUSTOM_ASSET_KEY",
apiKey: "API_KEY"
};
// Make load request to cast web receiver
const castSession = cast.framework.CastContext.getInstance().getCurrentSession();
const request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
() => { console.log('Load succeed'); },
(errorCode) => { console.log('Error code: ' + errorCode); });
Android
Per configurare questi valori in un mittente web Cast, crea innanzitutto un oggetto MediaInfo con i dati richiesti, quindi invia una richiesta di caricamento al ricevitore web.
JSONObject customData = new JSONObject()?
.put("daiStreamType", "DAI_STREAM_TYPE")
.put("networkCode", "NETWORK-CODE")
.put("customAssetKey", "CUSTOM_ASSET_KEY")
.put("apiKey", "API_KEY");
MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
.setContentUrl("BACKUP_STREAM_URL")
.setContentType("CONTENT_STREAM_MIMETYPE")
.setStreamType(MediaInfo.STREAM_TYPE_LIVE)
.setCustomData(customData)
.build();
RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());
iOS (Obj-C)
Per configurare questi valori in un mittente web Cast, crea prima un oggetto GCKMediaInformation con i dati richiesti, quindi invia una richiesta di caricamento al ricevitore web.
NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
@"daiStreamType": @"DAI_STREAM_TYPE",
@"networkCode": @"NETWORK-CODE",
@"customAssetKey": @"CUSTOM_ASSET_KEY",
@"apiKey": @"API_KEY"};
mediaInfoBuilder.customData = customData;
GCKMediaInformationBuilder *mediaInfoBuilder =
[[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeLive;
mediaInfoBuilder.customData = customData;
self.mediaInformation = [mediaInfoBuilder build];
GCKRequest *request = [self.sessionManager.currentSession.remoteMediaClient loadMedia:self.mediaInformation];
if (request != nil) {
request.delegate = self;
}
iOS (Swift)
Per configurare questi valori in un mittente web Cast, crea prima un oggetto GCKMediaInformation con i dati richiesti, quindi invia una richiesta di caricamento al ricevitore web.
let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
print("invalid mediaURL")
return
}
let customData = [
"daiStreamType": "DAI_STREAM_TYPE",
"networkCode": "NETWORK-CODE",
"customAssetKey": "CUSTOM_ASSET_KEY",
"region": "API_KEY"
]
let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.Live
mediaInfoBuilder.customData = customData
mediaInformation = mediaInfoBuilder.build()
guard let mediaInfo = mediaInformation else {
print("invalid mediaInformation")
return
}
if let request = sessionManager.currentSession?.remoteMediaClient?.loadMedia
(mediaInfo) {
request.delegate = self
}
Strumento CAC
Per configurare questi valori nello strumento Cast comando e controllo, fai clic sulla scheda Carica contenuti multimediali e imposta il tipo di richiesta di caricamento personalizzata su LOAD. Quindi sostituisci i dati JSON nell'area di testo con questo JSON:
{
"media": {
"contentId": "CONTENT_ID",
"contentUrl": "BACKUP_STREAM_URL",
"contentType": ""CONTENT_STREAM_MIMETYPE"",
"streamType": "LIVE",
"customData": {
"daiStreamType": "DAI_STREAM_TYPE",
"networkCode": "NETWORK-CODE",
"customAssetKey": "CUSTOM_ASSET_KEY",
"oAuthToken": "API_KEY"
}
}
}
Questa richiesta di caricamento personalizzata può essere inviata al ricevitore per testare il resto dei passaggi.
Crea un ricevitore CAF di base
Crea un ricevitore web personalizzato, come mostrato nella guida al ricevitore web personalizzato dell'SDK CAF.
Il codice del ricevitore dovrebbe avere il seguente aspetto:
<html>
<head>
<script
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
</script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
// ...
</script>
</body>
</html>
Importa l'SDK IMA DAI e ottieni il gestore del player
Aggiungi un tag di script per importare l'SDK IMA DAI per CAF nel tuo ricevitore web, subito dopo lo script che carica CAF. Nel tag di script, memorizza il contesto del ricevitore e il gestore del player come costanti prima di avviare il ricevitore.
<html>
<head>
<script
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
castContext.start();
</script>
</body>
</html>
Inizializza IMA Stream Manager
Inizializza IMA Stream Manager.
<html>
<head>
<script type="text/javascript"
src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
<script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
<cast-media-player></cast-media-player>
<script>
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const streamManager = new google.ima.cast.dai.api.StreamManager();
castContext.start();
</script>
</body>
</html>
Crea l'intercettatore di carico di Stream Manager
Prima che gli elementi multimediali vengano passati a CAF, crea la richiesta di stream in un intercettatore di messaggi LOAD.
const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();
const streamManager = new google.ima.cast.dai.api.StreamManager();
/**
* Creates a livestream request object for a Pod Serving stream.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {StreamRequest} an IMA stream request
*/
const createStreamRequest = (castRequest) => { /* ... */};
/**
* Initates a DAI stream request for the final stream manifest.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
*/
const createDAICastRequest = (castRequest) => {
return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
.then((castRequestWithPodStreamData) => {
console.log('Successfully made DAI stream request.');
// ...
return castRequestWithPodStreamData;
})
.catch((error) => {
console.log('Failed to make DAI stream request.');
// CAF will automatically fallback to the content URL
// that it can read from the castRequest object.
return castRequest;
});
};
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, createDAICastRequest);
castContext.start();
Crea la richiesta di stream
Completa la funzione createStreamRequest per creare uno stream Pod Serving basato sulla richiesta di caricamento CAF.
/**
* Creates a livestream request object for a Pod Serving stream.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {StreamRequest} an IMA stream request
*/
const createStreamRequest = (castRequest) => {
const customData = castRequest.media.customData;
let streamRequest;
if (customData.daiStreamType == "LIVE") {
streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
streamRequest.customAssetKey = customData.customAssetKey;
streamRequest.networkCode = customData.networkCode;
streamRequest.apiKey = customData.apiKey;
} else if (customData.daiStreamType == "VOD") {
streamRequest = new google.ima.cast.dai.api.PodVodStreamRequest();
streamRequest.networkCode = customData.networkCode;
streamRequest.apiKey = customData.apiKey;
}
return streamRequest;
};
Recupera il manifest unito dal VTP
Se la richiesta di stream va a buon fine, utilizza streamManager.getStreamId() per recuperare l'ID dello stream. Il tuo partner tecnico video (VTP) o il manipolatore di manifest personalizzato fornirà istruzioni per recuperare un URL manifest utilizzando questo ID stream.
Una volta recuperato l'URL del manifest, sostituisci l'contentUrl esistente con il nuovo manifestUrl.
Infine, prima di restituire il manifest dello stream modificato, chiama il metodo loadStreamMetadata su streamManager per informare l'SDK IMA che può richiedere in sicurezza i metadati dello stream. Questa chiamata è necessaria solo per gli stream VOD.
/**
* Initates a DAI stream request for the final stream manifest.
* @param {!LoadRequestData} castRequest The request object from the cast sender
* @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
*/
const createDAICastRequest = (castRequest) => {
return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
.then((castRequestWithPodStreamData) => {
console.log('Successfully made DAI stream request.');
// This is a sample VTP integration. Consult your VTP documentation
// for how to retrieve an ad-stitched stream manifest URL.
const manifestTemplate = "https://.../manifest.m3u8?gam_stream_id=[[STREAMID]]";
const streamId = streamManager.getStreamId();
const manifestUrl = manifestTemplate.replace('[[STREAMID]]', streamId)
// Assign your manifestUrl to the request's content URL.
castRequestWithPodStreamData.media.contentUrl = manifestUrl;
// After generating the manifest URL, VOD streams must notify the
// IMA SDK that it is safe to request ad pod metadata.
// This is only necessary for VOD streams. It is a no-op for
// livestreams, so no conditional is needed.
streamManager.loadStreamMetadata();
return castRequestWithPodStreamData;
})
.catch((error) => {
console.log('Failed to make DAI stream request.');
// CAF will automatically fallback to the content URL
// that it can read from the castRequest object.
return castRequest;
});
};
Esegui la pulizia degli asset IMA DAI
Dopo aver completato la richiesta e la visualizzazione degli annunci in uno stream di pubblicazione di pod con l'SDK IMA DAI, ti consigliamo di eseguire la pulizia di tutte le risorse al termine della sessione di pubblicazione di pod. Chiama StreamManager.destroy() per interrompere la riproduzione dello stream, interrompere tutto il monitoraggio degli annunci e rilasciare tutti gli asset dello stream caricati.