Usar o SDK do IMA DAI no Chromecast

Reproduzir transmissões ao vivo registradas com a API Google Cloud Video Stitcher

Este guia demonstra como usar o SDK DAI do IMA para receptores da Web do CAF para solicitar e reproduzir uma transmissão ao vivo de um evento registrado com a API Google Cloud Video Stitcher e inserir um intervalo de anúncio durante a reprodução.

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

Confira se o formato de streaming é compatível com os receptores da Web do CAF antes de continuar.

Para informações sobre a integração com outras plataformas ou o uso dos SDKs do lado do cliente do IMA, consulte SDKs do Interactive Media Ads.

Contexto

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

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

Componentes e arquitetura do app

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

  • VideoStitcherLiveStreamRequest: um objeto que define uma solicitação de transmissão para os servidores do Google. A solicitação especifica uma instância da API Cloud Video Stitcher, um ID de configuração em tempo real e outros parâmetros opcionais.
  • StreamManager: um objeto que processa a comunicação entre o stream de vídeo e o SDK do IMA DAI, como acionar pings de rastreamento e encaminhar eventos de stream para o editor.

Pré-requisitos

Você precisa das seguintes variáveis para o SDK do IMA:

  • ID da configuração ao vivo: é o ID da configuração ao vivo que você especificou ao criar a configuração ao vivo da API Video Stitcher.

    LIVE_CONFIG_ID

  • Local: a região do Google Cloud em que a Configuração ao vivo foi criada.

    LOCATION

  • Número do projeto: o número do projeto do Google Cloud que usa a API Video Stitcher.

    PROJECT_NUMBER

  • Token OAuth: um token 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

  • Network Code: é o código de rede do Google Ad Manager para solicitar anúncios.

    NETWORK_CODE

  • Chave de recurso personalizada: chave de recurso personalizada do Google Ad Manager gerada durante o processo de criação de uma configuração para um evento de transmissão ao vivo com a API Video Stitcher.

    CUSTOM_ASSET_KEY

Você precisa do seguinte para um receptor de transmissão personalizada:

Preparar um remetente para transmitir dados de fluxo ao receptor

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

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

CONTENT_ID
contentUrl URL de stream de backup opcional para exibição caso o stream da DAI não seja carregado.

BACKUP_STREAM_URL
contentType Mimetype opcional do URL do stream de backup a ser reproduzido se o stream da DAI falhar no carregamento.

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

LIVE
customData

O campo customData contém um armazenamento de chave-valor de campos obrigatórios adicionais. Nesse caso, customData contém os dados de fluxo de DAI que você coletou.

Campo Conteúdo
liveConfigID LIVE_CONFIG_ID
region LOCATION
projectNumber PROJECT_NUMBER
oAuthToken OAUTH_TOKEN
networkCode NETWORK_CODE
customAssetKey CUSTOM_ASSET_KEY

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

Web

Para configurar esses valores em um transmissor da Web do Google 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.LIVE;
mediaInfo.customData = {
liveConfigID: "LIVE_CONFIG_ID",
region: "LOCATION",
projectNumber: "PROJECT_NUMBER",
oAuthToken: "OAUTH_TOKEN",
networkCode: "NETWORK_CODE",
customAssetKey: "CUSTOM_ASSET_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

Para configurar esses valores em um transmissor da Web do Google 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("liveConfigID", "LIVE_CONFIG_ID")
  .put("region", "LOCATION")
  .put("projectNumber", "PROJECT_NUMBER")
  .put("oAuthToken", "OAUTH_TOKEN")
  .put("networkCode", "NETWORK_CODE")
  .put("customAssetKey", "CUSTOM_ASSET_KEY");

MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
  .setContentUrl("BACKUP_STREAM_URL")
  .setContentType("BACKUP_STREAM_MIMETYPE")
  .setStreamType(MediaInfo.STREAM_TYPE_LIVE)
  .setCustomData(customData)
  .build();

RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());

iOS (Objective-C)

Para configurar esses valores em um transmissor da Web do Google 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 = @{
  @"liveConfigID": @"LIVE_CONFIG_ID",
  @"region": @"LOCATION",
  @"projectNumber": @"PROJECT_NUMBER",
  @"oAuthToken": @"OAUTH_TOKEN",
  @"networkCode": @"NETWORK_CODE",
  @"customAssetKey": @"CUSTOM_ASSET_KEY"
};

GCKMediaInformationBuilder *mediaInfoBuilder =
  [[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"BACKUP_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)

Para configurar esses valores em um transmissor da Web do Google 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 = [
  "liveConfigID": "LIVE_CONFIG_ID",
  "region": "LOCATION",
  "projectNumber": "PROJECT_NUMBER",
  "oAuthToken": "OAUTH_TOKEN",
  "networkCode": "NETWORK_CODE",
  "customAssetKey": "CUSTOM_ASSET_KEY"
]

let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = "BACKUP_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
}

Ferramenta de CAC

Para configurar esses valores na ferramenta de comando e controle do Google 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": "LIVE",
    "customData": {
      "liveConfigID": "LIVE_CONFIG_ID",
      "region": "LOCATION",
      "projectNumber": "PROJECT_NUMBER",
      "oAuthToken": "OAUTH_TOKEN",
      "networkCode": "NETWORK_CODE",
      "customAssetKey": "CUSTOM_ASSET_KEY"
    }
  }
}

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

Criar um receptor da Web CAF personalizado

Crie um receptor da Web personalizado, conforme mostrado no Guia do receptor da Web personalizado do SDK do 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 do IMA DAI e acessar o Player Manager

Adicione uma tag de script para importar o SDK do DAI do IMA para CAF ao seu receptor da Web, logo após o script carregar o CAF. Em seguida, na tag de script a seguir, armazene o contexto do receptor e o gerenciador de jogadores 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 gerenciador de stream do IMA

Inicialize o Stream Manager do IMA.

<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 Stream Manager Load Interceptor

Antes que seus itens de mídia sejam transmitidos ao CAF, crie sua solicitação de transmissão 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 livestream 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 streaming

Conclua a função createStreamRequest para criar uma solicitação de transmissão ao vivo da API Video Stitcher com base na solicitação de carregamento do CAF.

    /**
     * Creates a livestream 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.VideoStitcherLiveStreamRequest();
      const customData = castRequest.media.customData;

      streamRequest.liveStreamEventId = customData.liveConfigID;
      streamRequest.region = customData.region;
      streamRequest.projectNumber = customData.projectNumber;
      streamRequest.oAuthToken = customData.oAuthToken;
      streamRequest.networkCode = customData.networkCode;
      streamRequest.customAssetKey = customData.customAssetKey;

      return streamRequest;
    };

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

Personalize sua solicitação de transmissão adicionando opções de sessão para substituir a configuração padrão da API Cloud Video Stitcher usando VideoStitcherLiveStreamRequest.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 abaixo, que solicita dois manifestos de transmissão com renditions ordenadas do bitrate mais baixo para o mais 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);
Anterior
Android
Próxima
HTML5