API Dynamic Ad Insert para transmissões ao vivo

Com a API Google DAI, é possível implementar streams ativados para DAI do Google em ambientes onde não há suporte para a implementação do SDK do IMA. Recomendamos que você ainda use o IMA nas plataformas compatíveis.

Recomendamos o uso da API DAI nas seguintes plataformas:

  • Smart TV Samsung (Tizen)
  • TV LG
  • HbbTV
  • Xbox (apps JavaScript)
  • KaiOS

A API é compatível com os recursos básicos fornecidos pelo SDK de DAI do IMA. Para perguntas específicas sobre compatibilidade ou recursos compatíveis, entre em contato com seu gerente de contas do Google.

Implementar a API DAI para transmissões AO VIVO

A API DAI é compatível com transmissões lineares (AO VIVO) que usam os protocolos HLS e DASH. As etapas descritas neste guia se aplicam aos dois protocolos.

Para integrar a API ao seu app para transmissões AO VIVO, siga estas etapas:

1. Solicitar um stream

Para solicitar uma transmissão ao vivo da API DAI, faça uma chamada POST para o endpoint de stream. A resposta JSON contém o manifesto de stream, além de endpoints e valores da API DAI associados.

Exemplo de corpo da solicitação

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Exemplo de corpo de resposta

{
"stream_id":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

Resposta de erro

Em caso de erros, os códigos de erro HTTP padrão são retornados sem corpo de resposta JSON.

Analise a resposta JSON e armazene os seguintes valores:

stream_id
Esse valor pode ser usado para identificar o stream retornado.
stream_manifest
Esse URL é transmitido ao player de mídia para reprodução da transmissão.
media_verification_url
Esse URL é o endpoint base para rastrear eventos de reprodução.
metadata_url
Esse URL é usado para pesquisar informações periódicas sobre os próximos eventos de transmissão.
session_update_url
Esse URL é usado para atualizar os parâmetros de solicitação de stream enviados durante a solicitação de stream inicial. Os parâmetros dessa solicitação substituem todos os parâmetros definidos para o stream anterior.
polling_frequency
A frequência, em segundos, ao solicitar metadados AdBreak atualizados da API DAI.

2. Pesquisa para novos metadados de intervalo de anúncios

Defina um timer para pesquisar novos metadados de AdBreak na frequência de pesquisa, usando o URL de metadados. Se não for especificado na resposta do stream, o intervalo padrão recomendado será de 10 segundos.

Exemplo de corpo da solicitação

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata

Exemplo de corpo de resposta

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },......
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },....
   }
}

3. Detectar eventos ID3 e rastrear eventos de reprodução

Para verificar se eventos específicos ocorreram em um stream de vídeo, siga estas etapas para processar eventos ID3:

  1. Armazene os eventos de mídia em uma fila, salvando cada ID de mídia com o carimbo de data/hora (se exibido pelo player).
  2. A cada atualização do player ou em uma frequência definida (recomendado 500 ms), verifique a fila de eventos de mídia para eventos reproduzidos recentemente comparando os carimbos de data/hora dos eventos com o marcador.
  3. No caso de eventos de mídia que você confirmar que foram reproduzidos, verifique o tipo procurando o ID da mídia nas tags de intervalo de anúncio armazenadas. Lembre-se de que as tags armazenadas contêm apenas um prefixo do ID da mídia. Por isso, não é possível estabelecer uma correspondência exata.
  4. Use eventos "progress" para monitorar se um usuário está dentro de um intervalo de anúncio. Não envie esses eventos para o endpoint de verificação de mídia. Para outros tipos de evento, anexe o ID da mídia ao endpoint de verificação de mídia e faça uma solicitação GET para rastrear a reprodução.
  5. Remove o evento de mídia da fila.

Exemplo de corpo da solicitação

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

Exemplos de respostas

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

Você pode verificar os eventos de rastreamento no Monitoramento de atividades de streaming.

4. Atualizar os parâmetros da sessão de transmissão ao vivo

É recomendável ajustar os parâmetros da sessão após a criação de um stream. Para isso, faça uma solicitação ao URL de atualização da sessão.

Exemplo de corpo da solicitação

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Exemplo de corpo de resposta

Successful response would be to look for - HTTP/1.1 200

Limitações

Ao usar a API em WebViews, as seguintes limitações se aplicam à segmentação:

  • UserAgent: o parâmetro do user agent é transmitido como um valor específico do navegador em vez da plataforma subjacente.
  • rdid, idtype, is_lat: o ID do dispositivo não foi transmitido corretamente, o que limita os recursos dos seguintes recursos:
    • Limite de frequência
    • Rotação de anúncios sequencial
    • Segmentação de público-alvo

Práticas recomendadas

Lembre-se de que o endpoint de metadados para índices de transmissão ao vivo é baseado no prefixo da tag ID3 correspondente. Isso foi projetado para evitar o uso do endpoint de metadados para dar um ping imediatamente em todos os nós de verificação.

Outros recursos