Configurar o SDK do IMA para DAI

Selecione a plataforma: HTML5 Android iOS tvOS Cast Roku

Selecione a solução de DAI que você quer usar

DAI de veiculação de conjunto

Os SDKs do IMA simplificam a integração de anúncios multimídia aos seus sites e apps.

Os SDKs do IMA podem solicitar anúncios de qualquer servidor de anúncios compatível com VAST e gerenciar a reprodução de anúncios nos seus apps.

Com os SDKs DAI do IMA, os apps fazem uma solicitação de stream para anúncios e vídeos de conteúdo para VOD ou conteúdo ao vivo. Em seguida, o SDK retorna um stream de vídeo combinado para que você não precise gerenciar a troca entre o anúncio e o vídeo de conteúdo no seu app.

Este guia demonstra como reproduzir um stream de veiculação de pod de DAI usando o SDK de DAI do IMA para CAF.

Antes de usar este guia, familiarize-se com o protocolo Web Receiver do Chromecast Application Framework. Este guia pressupõe uma compreensão básica dos conceitos do receptor do CAF, como interceptores de mensagens e objetos mediaInformation, além de familiaridade com o uso da ferramenta de comando e controle do Cast para emular um remetente do CAF.

Para usar a Veiculação de conjunto DAI da IMA, você precisa trabalhar com um parceiro de veiculação de conjunto e ter uma conta do Ad Manager 360 Advanced. Se você tiver uma conta do Ad Manager, entre em contato com seu gerente de contas para mais detalhes. Para saber como se inscrever no Ad Manager, acesse a Central de Ajuda do Ad Manager.

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

Visão geral da veiculação de conjunto DAI do IMA

A implementação do serviço de veiculação de pods usando o SDK DAI do CAF da IMA envolve dois componentes principais, que são demonstrados neste guia:

  • StreamRequest: um objeto que define uma solicitação de stream para os servidores de publicidade do Google. As solicitações especificam um código de rede, uma chave de recurso personalizada e uma chave de API opcional, além de outros parâmetros opcionais.
  • 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.

Pré-requisitos

Configurar os objetos MediaInfo do remetente

Primeiro, configure o objeto MediaInfo do app remetente para incluir os seguintes campos:

Campo Índice
contentId Um identificador exclusivo do item de mídia.

CONTENT_ID
contentUrl Opcional. URL do stream de backup a ser reproduzido se o stream da DAI não carregar.

BACKUP_STREAM_URL

contentType Opcional. Tipo MIME das transmissões de backup de conteúdo. Necessário apenas para streams DASH.

CONTENT_STREAM_MIMETYPE
streamType O literal de string ou a constante usada para esse valor varia de acordo com a plataforma do remetente.
customData O campo customData contém um armazenamento de chave-valor de outros campos obrigatórios. Neste exemplo, ele contém os parâmetros de stream da DAI. Em um app de produção, você pode transmitir um identificador que o app receptor do Cast usaria para recuperar esses parâmetros com uma solicitação do lado do servidor.
Campo Índice
daiStreamType O tipo de stream da DAI. Pode ser "LIVE" ou "VOD".

DAI_STREAM_TYPE
networkCode O código de rede da sua conta do Google Ad Manager 360.

NETWORK_CODE
customAssetKey Esse campo é necessário apenas para transmissões ao vivo. A chave de recurso personalizada que identifica seu evento de veiculação de podcast no Google Ad Manager 360.

CUSTOM_ASSET_KEY
apiKey Uma chave de API opcional para recuperar um ID de stream do SDK DAI do IMA.

API_KEY

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

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("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)

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 = @{
  @"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)

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 = [
  "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
}

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": ""CONTENT_STREAM_MIMETYPE"",
    "streamType": "LIVE",
    "customData": {
      "daiStreamType": "DAI_STREAM_TYPE",
      "networkCode": "NETWORK-CODE",
      "customAssetKey": "CUSTOM_ASSET_KEY",
      "oAuthToken": "API_KEY"
    }
  }
}

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

Criar um receptor do CAF básico

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>
    // ...
  </script>
</body>
</html>

Importar o SDK de DAI do IMA e receber o Player Manager

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. Na tag script, 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 StreamManager da 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 interceptor de carga do gerenciador de streams

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 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();

Criar a solicitação de stream

Conclua a função createStreamRequest para criar um stream de veiculação de pod com base na solicitação de carga do 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;
    };

Recupere o manifesto unificado do seu VTP.

Se a solicitação de transmissão for bem-sucedida, use streamManager.getStreamId() para recuperar o ID da transmissão. Seu parceiro técnico de vídeo (VTP) ou manipulador de manifesto personalizado vai fornecer instruções para recuperar um URL de manifesto usando esse ID de stream.

Depois de recuperar o URL do manifesto, substitua o contentUrl pelo novo manifestUrl.

Por fim, antes de retornar o manifesto de stream modificado, chame o método loadStreamMetadata no seu streamManager para informar ao SDK do IMA que ele pode solicitar metadados de stream com segurança. Essa chamada é necessária apenas para transmissões de 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;
          });
    };

Limpar recursos da DAI da IMA

Quando você terminar de solicitar e exibir anúncios em um fluxo de veiculação de pods com o SDK da DAI do IMA, recomendamos que limpe todos os recursos após a conclusão da sessão de veiculação de pods. Chame StreamManager.destroy() para interromper a reprodução de stream, parar todo o acompanhamento de anúncios e liberar todos os recursos de stream carregados.