Utilizzare l'SDK IMA DAI su Chromecast

Riproduci gli 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 amplia l'esempio di base del DAI con servizio completo, 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 del Web Receiver di Chromecast Application Framework.

Questa guida presuppone una conoscenza di base dei concetti relativi ai ricevitori CAF, come gli intercettatori di messaggi, gli oggetti MediaInformation e l'utilizzo dello strumento di controllo e comando di trasmissione 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 prevede due componenti principali, come dimostrato in questa guida:

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

Configura un progetto Google Cloud

Inserisci le seguenti variabili da utilizzare nell'SDK IMA:

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

    LOCATION

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

    PROJECT_NUMBER

  • Token OAuth: il 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 gli account di servizio.

    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 di configurazione VOD nella guida alla creazione di una configurazione VOD per Cloud Stitching.

    VOD_URI

Configurare un ricevitore di trasmissione personalizzato

Per sviluppare un ricevitore di trasmissione personalizzato, devi avere quanto segue:

Preparare un mittente per trasmettere i dati dello stream al destinatario

Innanzitutto, configura l'app mittente in modo che effettui una richiesta di caricamento al ricevitore web, contenendo i seguenti campi nell'oggetto MediaInformation della 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 di contenuti multimediali.

CONTENT_ID
contentUrl URL dello stream di backup facoltativo da riprodurre se lo stream DAI non riesce a caricarsi.

BACKUP_STREAM_URL
contentType Tipo MIME facoltativo dell'URL dello stream di backup da riprodurre se lo stream DAI non riesce a caricarsi.

BACKUP_STREAM_MIMETYPE
streamType La stringa letterale o la costante utilizzata per questo valore varia in base alla piattaforma di invio.

VOD
customData

Il campo customData contiene un archivio di coppie chiave-valore di campi obbligatori aggiuntivi. In questo caso, customData contiene i dati dello stream DAI raccolti.

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 di trasmissione, crea innanzitutto 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 = "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 di trasmissione, crea innanzitutto un oggetto MediaInfo con i dati richiesti, quindi invia 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 di trasmissione, crea innanzitutto 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 = @{
  @"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 di trasmissione, crea innanzitutto 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 = [
  "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 comandi di trasmissione, fai clic sulla scheda Carica contenuti multimediali e imposta il tipo di richiesta di caricamento personalizzato 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 personalizzato 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 sul 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>
    const castContext = cast.framework.CastReceiverContext.getInstance()
    castContext.start();
  </script>
</body>
</html>

Importa l'SDK DAI IMA e ottieni il gestore dei player

Aggiungi un tag script per importare l'SDK IMA DAI per CAF nel tuo ricevitore web, subito dopo il caricamento del CAF da parte dello script. Poi, nel tag script che segue, memorizza il contesto del ricevitore e il gestore dei giocatori 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>

Creare l'intercettatore del carico di Stream Manager

Prima che gli elementi multimediali vengano trasmessi a CAF, crea la richiesta di streaming 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 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 del 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 manifest con lo snippet di codice seguente, che richiede due manifest di stream con le rappresentazioni ordinate dalla maggiore alla minore velocità in bit.

...

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