Gerenciar transmissões ao vivo do DAI

A API DAI do Google permite implementar streams compatíveis com a DAI do Google em ambientes em que a implementação do SDK do IMA não é compatível. Recomendamos que você ainda use o IMA em plataformas compatíveis com o SDK do IMA.

Recomendamos usar a API DAI nas seguintes plataformas:

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

A API oferece suporte aos recursos básicos fornecidos pelo SDK DAI do IMA. Para dúvidas específicas sobre compatibilidade ou recursos disponí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 streams lineares (AO VIVO) usando 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. Pedir uma transmissão

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 dos endpoints e valores associados da API DAI.

Exemplo de corpo da solicitação

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

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

Exemplo de corpo da resposta

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

Resposta de erro

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

Analise a resposta JSON e armazene os seguintes valores:

stream_id
Esse valor pode ser usado para identificar o fluxo retornado.
stream_manifest
Esse URL é transmitido ao seu player de mídia para reprodução de stream.
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 inicial. Os parâmetros desta solicitação substituem todos os parâmetros definidos para o fluxo anterior.
polling_frequency
A frequência, em segundos, ao solicitar metadados atualizados de intervalo comercial da API DAI.

2. Pesquisar novos metadados de intervalo comercial

Defina um timer para pesquisar novos metadados de intervalo comercial 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.

Para otimizar a largura de banda, faça o seguinte:

  1. Faça uma solicitação GET inicial para o endpoint metadata_url.
    • Omita o parâmetro de consulta delta_token. Esse processo permite que o servidor retorne os metadados completos da janela do gravador de vídeo digital (DVR) da transmissão. A janela de DVR contém o período da transmissão disponível para um espectador retroceder e assistir. A resposta inclui um campo de objeto next_delta_token.
  2. Armazenar metadados no lado do cliente.
  3. Faça chamadas subsequentes usando o valor next_delta_token retornado pela resposta mais recente. Cada resposta contém um valor next_delta_token. Sempre envie o valor mais recente que você receber.
  4. Atualize os metadados armazenados para mesclar as mudanças e remover os intervalos de anúncios obsoletos.

Não tente analisar, construir ou modificar o token delta. O formato do token pode mudar. Armazene o token como recebido e transmita-o de volta inalterado na próxima solicitação.

Exemplo de solicitação inicial

A solicitação inicial não usa parâmetros de consulta e retorna os metadados completos:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

Exemplo de solicitação subsequente

Cada solicitação subsequente transmite o valor next_delta_token da resposta anterior como o parâmetro delta_token. A resposta contém o seguinte:

  • Anúncios
  • Intervalos de anúncio
  • Tags que o servidor adicionou ou atualizou desde que emitiu o token.
  • Uma lista obsolete_ad_break_ids de intervalos para anúncios a serem removidos dos metadados armazenados

O servidor omite intervalos de publicidade que não foram alterados. O exemplo a seguir mostra uma pesquisa subsequente usando o token delta para buscar apenas essas mudanças recentes:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

Se a operação for bem-sucedida, você vai ver uma saída semelhante a esta:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

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

Para verificar se eventos específicos ocorreram em um fluxo 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 mostrado pelo player).
  2. A cada atualização de tempo do player ou em uma frequência definida (recomendada 500 ms), verifique a fila de eventos de mídia para eventos reproduzidos recentemente comparando os carimbos de data/hora do evento com o marcador de reprodução.
  3. Para eventos de mídia que você confirmar que foram reproduzidos, verifique o tipo pesquisando o ID da mídia nas tags de intervalo de anúncio armazenadas. As tags armazenadas contêm apenas um prefixo do ID da mídia, então não é possível fazer uma correspondência exata.
  4. Como o app player de vídeo pesquisa o URL de metadados periodicamente, pode haver um atraso entre o momento em que o player encontra uma tag ID3 no stream e quando os metadados associados ficam disponíveis. Se uma tag ID3 não for encontrada nas tags armazenadas, mantenha-a em uma fila e reprocesse após a próxima pesquisa de metadados. Mantenha o evento na fila até que o processamento seja concluído.
  5. Depois de encontrar a tag nos metadados, verifique o campo type da tag em relação aos tipos de eventos de anúncio listados na seção a seguir. Para acompanhar se o player de vídeo está reproduzindo um intervalo de anúncio, use eventos com o valor progress do campo type. Não envie esses eventos para o endpoint de verificação de mídia. Para todos os outros tipos de eventos, anexe o ID de mídia ao endpoint de verificação de mídia e faça uma solicitação GET para rastrear a reprodução.
  6. Remova o evento de mídia da fila.

Tipos de evento de anúncio

Cada tag no objeto de metadados tags tem um dos seguintes tipos de evento:

Tipo de evento Descrição
start É executado no início do anúncio.
firstquartile É executado no final do primeiro quartil do anúncio.
midpoint É executado no ponto médio do anúncio.
thirdquartile É executado no final do terceiro quartil do anúncio.
complete É executado no final do anúncio.
progress Executado periodicamente durante um intervalo de anúncio para indicar que ele está sendo veiculado. Não envie esses eventos para o endpoint de verificação de mídia.

Exemplo de solicitação

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

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

É possível verificar os eventos de rastreamento no Monitor de atividade de streaming.

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

Talvez seja necessário ajustar os parâmetros de sessão depois que um fluxo for criado. 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/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

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

Exemplo de corpo da resposta

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

Limitações

Se você estiver usando a API em webviews, as seguintes limitações se aplicam em relação à segmentação:

  • UserAgent: o parâmetro 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 é transmitido corretamente, o que limita os recursos a seguir:
    • Limite de frequência
    • Rotação sequencial de anúncios
    • Segmentação de público-alvo

Práticas recomendadas

O endpoint de metadados para índices de transmissões ao vivo é baseado no prefixo da tag ID3 correspondente. Isso é proposital para evitar o uso do endpoint de metadados para fazer ping imediatamente em todos os nós de verificação.

Outros recursos