App de player de vídeo do cliente para streams de VOD

A API DAI Pod Serving do Google permite a inserção de anúncios do lado do servidor pelo Google Ads e, ao mesmo tempo, mantém o controle da combinação de vídeos.

Importante :antes de considerar essa API, verifique se já existe uma SDK de DAI da sua preferência. O SDK de DAI do IMA é recomendado em plataformas onde estão disponíveis. A API Pod Serving é usada apenas em plataformas que não têm um SDK de DAI do IMA.

Neste guia, mostramos como interagir com a API Pod Serving e conseguir funcionalidade semelhante com o SDK de DAI do IMA. Para perguntas específicas sobre compatível, entre em contato com seu gerente de contas do Google.

A API Pod Serving oferece suporte a streams de disponibilização de pods em HLS ou MPEG-DASH. protocolos de streaming de vídeo. Este guia se concentra nos streams HLS e destaca os principais diferenças entre HLS e MPEG-DASH em etapas específicas.

Para integrar a API Pod Serving ao seu app para streams de VOD, conclua o etapas a seguir:

Fazer uma solicitação de registro de stream ao Ad Manager

Faça uma solicitação POST para o endpoint de registro do stream. Você recebe, por sua vez, Resposta JSON contendo o ID de stream para enviar à manipulação do manifesto e os endpoints da API Pod Serving associados.

endpoint de API

POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Parâmetros de caminho

{network_code}

Seu código de rede do Google Ad Manager 360

Parâmetros do corpo do JSON

targeting_parameters

Um objeto JSON que contém o ID da origem do conteúdo (cmsid), ID do vídeo (vid) e segmentação de anúncios parâmetros. Obrigatório

JSON de resposta

media_verification_url	O URL base para dar um ping em eventos de rastreamento de reprodução. Uma verificação de mídia completa O URL é formado pela anexação de um ID de evento de anúncio a esse URL de base.
metadata_url	O URL para solicitar metadados do conjunto de anúncios.
stream_id	A string usada para identificar a sessão de transmissão atual.
valid_for	O tempo restante até o término da sessão de transmissão atual em dhms (dias, horas, minutos, segundos). Por exemplo: 2h0m0.000s representa uma duração de duas horas.
valid_until	O horário em que a sessão de stream atual expira, como um ISO 8601 string de data e hora em yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .

Exemplo de solicitação (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

Exemplo de resposta

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

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

Analise a resposta JSON e armazene os valores relevantes.

Dica :os URLs fornecidos na resposta da API estão sujeitos a mudanças sem aviso. Portanto, use os URLs conforme fornecidos na resposta da API em vez de construindo você mesmo. Isso ajuda a garantir que seu código continue funcionando corretamente quando os URLs mudam.

Solicitar o manifesto de stream do manipulador de manifesto

Cada manipulador de manifesto tem formatos diferentes de solicitação e resposta. Contato seu manipulador para entender os requisitos específicos dele. Se você estiver implementar seu próprio manipulador de manifesto, leia o manipulador de manifesto guia para entender requisitos para este componente.

Em geral, é necessário transmitir o ID de fluxo que foi retornado pelo o endpoint de registro acima ao manipulador de manifesto para que ele seja criado manifestos específicos da sessão. A menos que explicitamente declarado pelo manifesto manipulador, a resposta à solicitação do manifesto é um stream de vídeo que contém conteúdo e anúncios.

Exemplo de solicitação (cURL)

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

Exemplo de resposta (HLS)

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

Assistir a transmissão

Carregue o manifesto que você recebeu do servidor de manipulação de manifesto em um e inicie a reprodução.

Solicitar metadados do conjunto de anúncios do Ad Manager

Faça uma solicitação GET ao metadata_url que você recebeu na etapa 1. Isso deve ocorrer após o recebimento do manifesto integrado do manifesto. manipulador. Em troca, você recebe um objeto JSON contendo o seguinte parâmetros:

tags	Um conjunto de pares de chave-valor que contém todos os eventos de anúncio que aparecem na riacho. As chaves são os primeiros 17 caracteres de um evento de anúncio Código que aparece nos metadados com marcação de tempo do stream ou no caso de eventos do tipo progress, o ID completo do evento de anúncio. Cada valor é um objeto que contém os seguintes parâmetros: ad O ID de um anúncio que corresponde a uma chave no objeto ads. ad_break_id É o ID de um intervalo de anúncio que corresponde a uma chave no ad_breaks. objeto. type O tipo de evento de anúncio. Os tipos de evento de anúncio são: start Disparado no início do anúncio. firstquartile Disparado no final do primeiro quartil. midpoint Disparado no ponto médio do anúncio. thirdquartile Disparado no final do terceiro quartil. complete Disparado no final do anúncio. progress Disparado periodicamente durante todo o anúncio para notificar o app de que um anúncio está tocando.
ads	Um conjunto de pares de chave-valor que descreve todos os anúncios que aparecem no stream. A chaves são IDs de anúncios que correspondem aos valores encontrados no objeto tags listados acima. Cada valor é um objeto que contém os seguintes parâmetros: ad_break_id É o ID de um intervalo de anúncio que corresponde a uma chave no ad_breaks. objeto. position A posição em que este anúncio é exibido no conjunto de anúncios do mesmo em intervalos de segundos, em segundos de ponto flutuante. duration A duração do anúncio em segundos de ponto flutuante. clickthrough_url É o URL que deve abrir quando um usuário interagir com o anúncio, se compatível.
ad_breaks	Um conjunto de pares de chave-valor que descreve todos os intervalos de anúncio que aparecem no stream. As chaves são IDs de intervalo de anúncio que correspondem aos valores encontrados nos tags. e ads listados acima. Cada valor é um objeto que contêm os seguintes parâmetros: type O tipo de intervalo de anúncio. Os tipos de intervalo de anúncio são pre (precedente), mid (anúncio intermediário) e post (anúncio final). duration É a duração do intervalo de anúncio em segundos de ponto flutuante. ads O número de anúncios neste intervalo.

Armazene esses valores para associar a eventos de metadados com marcação de tempo no seu vídeo riacho.

Exemplo de solicitação (cURL)

curl https://dai.google.com/.../metadata

Exemplo de resposta

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

Detectar eventos de anúncio

Detectar metadados com marcação de tempo usando eventos de anúncios acionados no stream de áudio/vídeo do seu player de vídeo.

Para streams MPEG-TS, os metadados aparecem como tags ID3 v2.3 na banda. Cada a tag de metadados tem o ID TXXX, e o valor começa com a string google_ seguida por uma série de caracteres. Esse valor é o ID do evento de anúncio.

O XXX em TXXX não é um marcador de posição. A string TXXX é o ID da tag ID3. reservados para "texto definido pelo usuário".

Exemplo de tag ID3

TXXXgoogle_1234567890123456789

Para streams em MP4, eles são enviados como eventos emsg na banda que emulam ID3 v2.3 . Cada caixa de emsg relevante tem um valor scheme_id_uri de https://aomedia.org/emsg/ID3 ou https://developer.apple.com/streaming/emsg-id3 e um valor message_data começando com ID3TXXXgoogle_. Esse valor message_data, sem o ID3TXXX é o ID do evento de anúncio.

Exemplo de caixa de emsg

A estrutura de dados pode variar, dependendo da biblioteca do seu player de mídia.

Se o ID do evento de anúncio for google_1234567890123456789, a resposta será semelhante a esta: isso:

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

Algumas bibliotecas de player de mídia apresentam automaticamente eventos emsg que emulam ID3 como tags ID3 nativas. Nesse caso, as transmissões em MP4 apresentam tags ID3 idênticas como MPEG_TS.

Atualizar a interface do app de player de vídeo cliente

Cada ID de evento de anúncio pode ser associado a uma chave no objeto tags da etapa 4. A correspondência desses valores é um processo de duas etapas:

1. Verifique no objeto tags uma chave correspondente ao ID completo do evento do anúncio. Se uma correspondência for encontrada, recupere o tipo de evento e o ad associado e objetos ad_break. Esses eventos precisam ter o tipo progress.

   Se não for encontrada uma correspondência para o ID completo do evento de anúncio, verifique o tags objeto para uma chave que corresponde aos primeiros 17 caracteres da ID do evento de anúncio. Recupere o tipo de evento e os objetos ad e ad_break associados. Isso recupera todos os eventos com tipos diferentes de progress.

2. Use essas informações recuperadas para atualizar a interface do jogador. Por exemplo, quando você receber um evento start ou o primeiro progress, oculte a busca do jogador e exibe uma sobreposição que descreve a posição atual do anúncio na intervalo de anúncio, por exemplo: "Anúncio 1 de 3".

Exemplos de IDs de evento de anúncio

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

Exemplo de objeto de tags

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

Enviar pings de verificação de mídia

É preciso enviar um ping de verificação de mídia ao Ad Manager sempre que um evento de anúncio com um tipo diferente de progress é recebido.

Para gerar o URL completo de verificação de mídia de um evento de anúncio, anexe o ID do evento de anúncio para o valor media_verification_url do registro de stream resposta.

Faça uma solicitação GET com o URL completo. Se a solicitação de verificação for bem-sucedido, você receberá uma resposta HTTP com o código de status 202. Caso contrário, você receberá o código de erro HTTP 404.

Dica :eventos de anúncios do tipo progress não podem ser enviados ao Ad Manager. Esses são destinados a informar ao app de player de vídeo cliente que um intervalo de anúncio está em situações nas quais o evento de início pode não ter sido recebido. Por exemplo, se o usuário buscar uma posição ou iniciar a reprodução em um determinado que está no meio de um anúncio, eles não receberão um evento de início. Os eventos de progresso enviados ao Ad Manager são descartados e podem afetar negativamente no desempenho de um app.

Exemplo de solicitação (cURL)

curl https://{...}/media/google_5555555555123456789

Exemplo de resposta bem-sucedida

HTTP/1.1 202 Accepted

Outros recursos

• Documentação do SDK do IMA
• Tipos de implementação de player da DAI comparação