Configurar o SDK do IMA para DAI

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 pods da DAI usando o SDK DAI da 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 o gerente dela 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 da IMA

A implementação do serviç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 para este 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, que é "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 do IMA DAI.

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 básico do CAF

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 de 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 de 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 pods 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 pod com o SDK de DAI do IMA, recomendamos que você limpe todos os recursos após a conclusão da sessão de veiculação de pod. Chame StreamManager.destroy() para interromper a reprodução de stream, parar todo o rastreamento de anúncios e liberar todos os recursos de stream carregados.