Usar o SDK do IMA DAI no Chromecast

Reproduzir transmissões de VOD registradas com a API Video Stitcher do Google Cloud

Este guia demonstra como usar o SDK DAI do IMA para receptores da Web do CAF para solicitar e reproduzir uma sessão de streaming de VOD do Google Cloud.

Este guia amplia o exemplo básico da DAI de serviço completo, adicionando suporte para streams registrados com a API Google Cloud Video Stitcher.

Antes de continuar, verifique se o formato de streaming é compatível com os receptores da Web do CAF.

Para informações sobre como integrar a outras plataformas ou usar os SDKs do IMA do lado do cliente, consulte SDKs do Interactive Media Ads.

Contexto

Antes de usar este guia, familiarize-se com o protocolo Web Receiver do Chromecast Application Framework.

Este guia pressupõe um nível básico de familiaridade com os conceitos do receptor do CAF, como interceptores de mensagens, objetos MediaInformation e o uso da ferramenta de comando e controle do Cast para emular um remetente do CAF.

Componentes e arquitetura do app

A implementação da reprodução de stream VOD com a API Google Cloud Video Stitcher e o SDK do IMA CAF DAI envolve dois componentes principais, conforme demonstrado neste guia:

  • VideoStitcherVodStreamRequest: um objeto que define uma solicitação de transmissão para os servidores do Google.
  • StreamManager: um objeto que processa a comunicação entre o stream de vídeo e o SDK DAI do IMA, como o disparo de pings de rastreamento e o encaminhamento de eventos de stream para o publisher.

Configure um projeto do Google Cloud

Insira as seguintes variáveis para uso no SDK do IMA:

  • Local: a região do Google Cloud em que sua configuração de VOD foi criada.

    LOCATION

  • Número do projeto: o número do projeto na nuvem do Google Cloud usando a API Video Stitcher.

    PROJECT_NUMBER

  • Token do OAuth: um token do OAuth de curta duração de uma conta de serviço com a função de usuário do Video Stitcher. Saiba mais sobre como criar credenciais de curta duração para contas de serviço.

    OAUTH_TOKEN

  • Código de rede: código de rede do Google Ad Manager para solicitar anúncios.

    NETWORK_CODE

  • ID da configuração de VOD: o ID da configuração de VOD para a transmissão de VOD.

    VOD_CONFIG_ID

    Leia mais sobre como criar o ID de configuração de VOD no guia de criação de uma configuração de VOD de junção na nuvem.

    VOD_URI

Configurar um receptor de transmissão personalizado

Para desenvolver um receptor de transmissão personalizado, você precisa do seguinte:

Prepare um remetente para transmitir dados ao destinatário

Primeiro, configure o app remetente para fazer uma solicitação de carregamento ao receptor da Web, contendo os seguintes campos no objeto MediaInformation da plataforma.

Campo Índice
contentId Um identificador exclusivo para este item de mídia, conforme definido na documentação de referência do Cast. Ele não pode ser reutilizado para vários itens na mesma fila de mídia.

CONTENT_ID
contentUrl URL opcional da transmissão de backup a ser reproduzido se a transmissão da DAI não carregar.

BACKUP_STREAM_URL
contentType MIME type opcional do URL da transmissão de backup a ser reproduzido se a transmissão da DAI não carregar.

BACKUP_STREAM_MIMETYPE
streamType O literal de string ou a constante usada para esse valor varia de acordo com a plataforma do remetente.

VOD
customData

O campo customData contém um repositório de chave-valor de outros campos obrigatórios. Nesse caso, customData contém os dados de stream da DAI que você coletou.

Campo Índice
region LOCATION
projectNumber PROJECT_NUMBER
oAuthToken OAUTH_TOKEN
networkCode NETWORK_CODE
vodConfigId VOD_CONFIG_ID

Confira alguns exemplos de código para ajudar você a começar:

Web

Para configurar esses valores em um remetente da Web do Cast, primeiro crie um objeto MediaInfo com os dados necessários e faça uma solicitação de carregamento para o receptor da 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

Para configurar esses valores em um remetente da Web do Cast, primeiro crie um objeto MediaInfo com os dados necessários e faça uma solicitação de carregamento para o receptor da 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)

Para configurar esses valores em um remetente da Web do Cast, primeiro crie um objeto GCKMediaInformation com os dados necessários e faça uma solicitação de carregamento para o receptor da 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)

Para configurar esses valores em um remetente da Web do Cast, primeiro crie um objeto GCKMediaInformation com os dados necessários e faça uma solicitação de carregamento para o receptor da 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
}

Ferramenta de CAC

Para configurar esses valores na ferramenta de comando e controle do Cast, clique na guia "Carregar mídia" e defina o tipo de solicitação de carregamento personalizado como LOAD. Em seguida, substitua os dados JSON na área de texto por este 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"
    }
  }
}

Essa solicitação de carga personalizada pode ser enviada ao receptor para testar o restante das etapas.

Criar um receptor da Web do CAF personalizado

Crie um receptor da Web personalizado, conforme mostrado no Guia do receptor da Web personalizado do SDK CAF.

O código do receptor vai ficar assim:

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

Importar o SDK de DAI do IMA e receber o gerenciador de players

Adicione uma tag script para importar o SDK do IMA DAI para CAF ao seu receptor da Web, logo após o script carregar o CAF. Em seguida, na tag script a seguir, armazene o contexto do receptor e o gerenciador de player como constantes antes de iniciar o receptor.

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

Inicializar o Stream Manager da IMA

Inicialize o 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>

Criar o interceptor de carga do Stream Manager

Antes que seus itens de mídia sejam transmitidos para o CAF, crie a solicitação de stream em um interceptador de mensagens 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();

Criar a solicitação de stream

Conclua a função createStreamRequest para criar uma solicitação de stream VOD da API Video Stitcher com base na solicitação de carregamento do 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;
    };

(Opcional) Adicionar opções de sessão de streaming

Personalize sua solicitação de stream adicionando opções de sessão para substituir a configuração padrão da API Cloud Video Stitcher usando VideoStitcherVodStreamRequest.videoStitcherSessionOptions. Se você fornecer uma opção não reconhecida, a API Cloud Video Stitcher vai responder com um erro HTTP 400. Consulte o guia de solução de problemas para receber ajuda.

Por exemplo, é possível substituir as opções de manifesto com o snippet de código a seguir, que solicita dois manifestos de stream com renderizações ordenadas do menor para o maior bitrate.

...

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

streamManager.requestStream(streamRequest);
Anterior
Android
Avançar
HTML5