Utilizzare l'SDK IMA DAI su Chromecast

Riproduci stream VOD registrati con l'API Google Cloud Video Stitcher

Questa guida mostra come utilizzare l'SDK IMA DAI per i ricevitori web CAF per richiedere e riprodurre una sessione di streaming VOD di Google Cloud.

Questa guida espande l'esempio di base della DAI full service, aggiungendo il supporto per gli stream registrati con l'API Google Cloud Video Stitcher.

Prima di continuare, assicurati che il formato di streaming sia supportato dai ricevitori web CAF.

Per informazioni sull'integrazione con altre piattaforme o sull'utilizzo degli SDK lato client IMA, consulta SDK Interactive Media Ads.

Sfondo

Prima di utilizzare questa guida, acquisisci familiarità con il protocollo Web Receiver del framework dell'applicazione Chromecast.

Questa guida presuppone una conoscenza di base dei concetti del ricevitore CAF, come gli intercettori di messaggi, gli oggetti MediaInformation e l'utilizzo dello strumento di comando e controllo di Cast per emulare un mittente CAF.

Componenti e architettura dell'app

L'implementazione della riproduzione di stream VOD con l'API Google Cloud Video Stitcher con l'SDK IMA CAF DAI comporta due componenti principali, come illustrato in questa guida:

  • VideoStitcherVodStreamRequest: Un oggetto che definisce una richiesta di flusso ai server di Google.
  • StreamManager: Un oggetto che gestisce la comunicazione tra lo stream video e l'SDK IMA DAI, ad esempio l'attivazione di ping di monitoraggio e l'inoltro di eventi di stream al publisher.

Configura un progetto Google Cloud

Inserisci le seguenti variabili da utilizzare nell'SDK IMA:

  • Posizione: la regione Google Cloud in cui è stata creata la configurazione VOD.

    LOCATION

  • Numero di progetto: il numero di progetto Google Cloud che utilizza l'API Video Stitcher.

    PROJECT_NUMBER

  • Token OAuth: token OAuth di breve durata di un account di servizio con il ruolo utente Video Stitcher. Scopri di più sulla creazione di credenziali di breve durata per i service account.

    OAUTH_TOKEN

  • Network Code: codice di rete Google Ad Manager per la richiesta di annunci.

    NETWORK_CODE

  • ID configurazione VOD: l'ID configurazione VOD per lo stream VOD.

    VOD_CONFIG_ID

    Scopri di più sulla creazione dell'ID configurazione VOD nella Guida alla creazione di una configurazione VOD di Cloud Stitching.

    VOD_URI

Configurare un ricevitore personalizzato

Per sviluppare un ricevitore Cast personalizzato, devi disporre di:

Prepara un mittente per trasmettere i dati dello stream al destinatario

Innanzitutto, configura l'app mittente per effettuare una richiesta di caricamento al ricevitore web, contenente i seguenti campi nell'oggetto MediaInformation della tua piattaforma.

Campo Sommario
contentId Un identificatore univoco per questo elemento multimediale, come definito nella documentazione di riferimento di Cast. Questo ID non deve essere riutilizzato per più elementi nella stessa coda multimediale.

CONTENT_ID
contentUrl URL dello stream di backup facoltativo da riprodurre se lo stream DAI non viene caricato.

BACKUP_STREAM_URL
contentType (Facoltativo) Tipo MIME dell'URL dello stream di backup da riprodurre se lo stream DAI non viene caricato.

BACKUP_STREAM_MIMETYPE
streamType Il valore letterale stringa o la costante utilizzata per questo valore varia in base alla piattaforma del mittente.

VOD
customData

Il campo customData contiene un archivio chiave-valore di campi obbligatori aggiuntivi. In questo caso, customData contiene i dati del flusso DAI che hai raccolto.

Campo Sommario
region LOCATION
projectNumber PROJECT_NUMBER
oAuthToken OAUTH_TOKEN
networkCode NETWORK_CODE
vodConfigId VOD_CONFIG_ID

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 web receiver.

// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "BACKUP_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.VOD;
mediaInfo.customData = {
  region: "LOCATION",
  projectNumber: "PROJECT_NUMBER",
  oAuthToken: "OAUTH_TOKEN",
  networkCode: "NETWORK_CODE",
  vodConfigId: "VOD_CONFIG_ID"
};

// 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 prima un oggetto MediaInfo con i dati richiesti, quindi effettua una richiesta di caricamento al ricevitore web.

JSONObject customData = new JSONObject()
  .put("region", "LOCATION")
  .put("projectNumber", "PROJECT_NUMBER")
  .put("oAuthToken", "OAUTH_TOKEN")
  .put("networkCode", "NETWORK_CODE")
  .put("vodConfigId", "VOD_CONFIG_ID");

MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
  .setContentUrl("BACKUP_STREAM_URL")
  .setContentType("BACKUP_STREAM_MIMETYPE")
  .setStreamType(MediaInfo.STREAM_TYPE_VOD)
  .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 web receiver.

NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
  @"region": @"LOCATION",
  @"projectNumber": @"PROJECT_NUMBER",
  @"oAuthToken": @"OAUTH_TOKEN",
  @"networkCode": @"NETWORK_CODE",
  @"vodConfigId": @"VOD_CONFIG_ID"
};

GCKMediaInformationBuilder *mediaInfoBuilder =
  [[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"BACKUP_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeNone;
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 web receiver.

let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
  print("invalid mediaURL")
  return
}

let customData = [
  "region": "LOCATION",
  "projectNumber": "PROJECT_NUMBER",
  "oAuthToken": "OAUTH_TOKEN",
  "networkCode": "NETWORK_CODE",
  "vodConfigId": "VOD_CONFIG_ID"
]

let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = "BACKUP_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.none
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 di controllo e comando di trasmissione, 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": "BACKUP_STREAM_MIMETYPE",
    "streamType": "VOD",
    "customData": {
      "region": "LOCATION",
      "projectNumber": "PROJECT_NUMBER",
      "oAuthToken": "OAUTH_TOKEN",
      "networkCode": "NETWORK_CODE",
      "vodConfigId": "VOD_CONFIG_ID"
    }
  }
}

Questa richiesta di caricamento personalizzata può essere inviata al destinatario per testare il resto dei passaggi.

Crea un ricevitore web CAF personalizzato

Crea un ricevitore web personalizzato, come descritto nella guida all'SDK CAF Custom Web Receiver.

Il codice del destinatario dovrebbe avere l'aspetto seguente:

<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>
    const castContext = cast.framework.CastReceiverContext.getInstance()
    castContext.start();
  </script>
</body>
</html>

Importa l'SDK IMA DAI e ottieni Player Manager

Aggiungi un tag di script per importare l'SDK IMA DAI per CAF nel ricevitore web, subito dopo il caricamento dello script CAF. Nella tag di script che segue, 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 caricamento di Stream Manager

Prima che gli elementi multimediali vengano passati a CAF, crea la richiesta di flusso in un intercettore di messaggi LOAD.

    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    /**
     * Creates a VOD stream request object for the Video Stitcher API.
     * @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((castRequestWithStreamData) => {
            console.log('Successfully made DAI stream request.');
            return castRequestWithStreamData;
          })
          .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 una richiesta di stream VOD dell'API Video Stitcher in base alla richiesta di caricamento CAF.

    /**
     * Creates a VOD stream request object for the Video Stitcher API.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {StreamRequest} an IMA stream request
     */
    const createStreamRequest = (castRequest) => {
      const streamRequest = new google.ima.cast.dai.api.VideoStitcherVodStreamRequest();
      const customData = castRequest.media.customData;

      streamRequest.region = customData.region;
      streamRequest.projectNumber = customData.projectNumber;
      streamRequest.oAuthToken = customData.oAuthToken;
      streamRequest.networkCode = customData.networkCode;
      streamRequest.vodConfigId = customData.vodConfigId;
      streamRequest.videoStitcherSessionOptions = {};

      return streamRequest;
    };

(Facoltativo) Aggiungi opzioni per la sessione di streaming

Personalizza la richiesta di stream aggiungendo opzioni di sessione per eseguire l'override della configurazione predefinita dell'API Cloud Video Stitcher utilizzando VideoStitcherVodStreamRequest.videoStitcherSessionOptions. Se fornisci un'opzione non riconosciuta, l'API Cloud Video Stitcher risponderà con un errore HTTP 400. Per assistenza, consulta la guida alla risoluzione dei problemi.

Ad esempio, puoi sostituire le opzioni del manifest con il seguente snippet di codice, che richiede due manifest di stream con rendizioni ordinate dal bitrate più basso a quello più alto.

...

// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
  "manifestOptions": {
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);
Indietro
Android
Avanti
HTML5