Usar uma integração personalizada

Antes de começar

Este documento abrange apenas as instruções de reprodução na ausência do SDK do DAI do IMA.

Verifique se você já concluiu as etapas em Integrar o Google Ad Manager (GAM) com os recursos de VOD antes.

Observação: recomendamos o uso do SDK DAI do IMA em plataformas com suporte.

Se o SDK do IMA não estiver disponível para a plataforma pretendida, será necessário que o aplicativo chame as APIs necessárias e acione as verificações de mídia de anúncio por conta própria.

Para isso, você vai precisar das seguintes informações:

Local	A região do Google Cloud em que a configuração ativa foi criada: LOCATION
Número do projeto	O número do projeto do Google Cloud que usa a API Video Stitcher: PROJECT_NUMBER
Token OAuth	Um token OAuth de curta duração de uma conta de serviço com a função de usuário do Video Stitcher: OAUTH_TOKEN Saiba mais sobre como criar tokens OAuth de curta duração. Importante:o token OAuth pode ser reutilizado em várias solicitações, desde que não tenha expirado.
Código da rede	O código de rede do Ad Manager para solicitar anúncios: NETWORK_CODE
ID da configuração VOD	O ID de configuração de VOD que você especificou ao criar o evento de stream de VOD: VOD_CONFIG_ID

Faça uma solicitação de registro de stream para o Ad Manager

Faça uma solicitação POST para o endpoint de registro de fluxo. Em troca, você recebe uma resposta JSON contendo o ID do stream a ser enviado ao servidor de manipulação de manifesto e aos endpoints da API de fornecimento de pods 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 de corpo codificados em JSON

targeting_parameters

Um conjunto de parâmetros de segmentação codificados em JSON.

JSON de resposta

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

Exemplo de solicitação (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

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 corpo de resposta JSON.

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 fornecidos na resposta da API em vez de criá-los você mesmo. Isso ajuda a garantir que o código continue funcionando corretamente quando os URLs mudarem.

Gerar uma sessão VOD do Cloud Video Stitcher

Faça uma solicitação POST para o endpoint de registro de sessão de VOD. Em troca, você recebe uma resposta JSON com o URI do manifesto de streaming e os metadados sobre intervalos comerciais, anúncios e eventos de anúncios.

endpoint de API

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

Parâmetros de caminho

PROJECT_NUMBER	Seu número do projeto do Google Cloud.
LOCATION	Sua região do Google Cloud.
NETWORK CODE	Seu código de rede do Google Ad Manager 360.

Parâmetros de corpo codificados em JSON

vodConfig	Uma string que contém o número do projeto, o local e o ID da configuração de VOD com o seguinte formato: projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID
adTracking	Defina como "CLIENT" para ativar o rastreamento do lado do cliente.
gamSettings	Um objeto que contém o código de rede e o ID do stream com o seguinte formato: { "networkCode":"NETWORK_CODE", "streamId":"STREAM_ID" }

JSON de resposta

name	O nome da sessão VOD, que contém o ID da sessão.
playUri	O URI do manifesto de stream costurado, para carregar no player de vídeo para reprodução. SESSION_PLAYBACK_URI
adTracking	O mesmo valor adTracking enviado para a API no corpo da solicitação.
vodConfig	A mesma string vodConfig enviada para a API no corpo da solicitação.
gamSettings	O mesmo objeto gamSettings enviado para a API no corpo da solicitação.

Exemplo de solicitação (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

Exemplo de resposta

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

Depois que a resposta for recebida, você poderá reproduzir a transmissão ao vivo com anúncios fazendo referência ao URI do campo playUri do objeto de resposta.

Solicitar metadados do conjunto de anúncios do Ad Manager

Faça uma solicitação GET para o metadata_url que você recebeu quando registrou seu stream no Ad Manager. Essa etapa precisa ocorrer depois que você receber o manifesto unido do URI de reprodução.

Em troca, você recebe um objeto JSON que descreve as pausas de publicidade, os anúncios e os eventos de publicidade do stream.

Endpoint da API

GET: METADATA_URL
Host: dai.google.com

JSON de resposta

tags	Um conjunto de pares de chave-valor que descrevem eventos de mídia de anúncios que vão ocorrer no stream. Cada chave consiste nos primeiros 17 caracteres de um ID de mídia de anúncio que vai aparecer nos metadados ID3 do fluxo ou, no caso de eventos de "progresso", o ID de mídia de anúncio completo. Cada valor é um objeto com as seguintes propriedades: ad: o ID do anúncio que contém o evento de mídia do anúncio. ad_break_id: o ID do intervalo de anúncio que contém o evento de mídia do anúncio. type: o tipo de evento de mídia de anúncio. Os valores são um dos seguintes: start: o anúncio foi iniciado firstquartile: o anúncio está 25% concluído. midpoint: o anúncio está 50% concluído. thirdquartile: o anúncio está 75% concluído. complete: o anúncio foi encerrado. progress: é disparado a cada segundo enquanto um anúncio está sendo reproduzido.
ads	Um conjunto de pares de chave-valor que descrevem os anúncios que vão aparecer no stream. Cada chave é um ID de anúncio. Cada valor é um objeto com as seguintes propriedades: ad_break_id: o ID do intervalo de anúncio que contém o evento de mídia do anúncio. position: a posição do anúncio no intervalo de anúncio. O primeiro anúncio em um intervalo tem uma posição de 1. duration: a duração do anúncio em segundos de ponto flutuante. title: o título do anúncio, conforme definido no VAST. description: a descrição do anúncio, conforme definido no VAST. ad_system: o sistema de anúncios, conforme definido no VAST. ad_system: o ID do anúncio, conforme definido no VAST. ad_system: o ID do criativo, conforme definido no VAST. clickthrough_url: o URL que será aberto quando um usuário interagir com o anúncio. universal_ad_id: um objeto que representa o ID universal do anúncio, conforme definido no VAST.
ad_breaks	Um conjunto de pares de chave-valor que descrevem os intervalos de anúncios que vão ocorrer no stream. Cada chave é um ID de intervalo de anúncio. Cada valor é um objeto com as seguintes propriedades: type: o tipo de intervalo de anúncio. Os valores serão um dos seguintes: pre: representa um anúncio precedente. mid: representa um anúncio intermediário. post: representa um anúncio final. duration: a duração do intervalo de anúncio em segundos de ponto flutuante. expected_duration: a duração esperada do intervalo em segundos de ponto flutuante. ads: o número de anúncios contidos no intervalo de anúncio.

Exemplo de solicitação (cURL)

curl METADATA_URL

Exemplo de resposta JSON

{
  "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
    },
    ...
  }
}

Armazene esses valores para associar a eventos de metadados temporizados no seu stream de vídeo.

Ouvir eventos ID3 e eventos de reprodução da faixa

Para verificar se eventos específicos ocorreram em uma transmissão 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. Em cada atualização de tempo do player ou em uma frequência definida (500 ms recomendado), verifique a fila de eventos de mídia para eventos reproduzidos recentemente comparando os carimbos de data/hora do evento com o indicador de reprodução.
3. Para eventos de mídia que você confirma que foram reproduzidos, verifique o tipo procurando o ID de mídia nas tags de intervalo de anúncio armazenadas. Lembre-se de que o objeto de tags de intervalo de anúncio contém apenas uma versão truncada do ID de mídia, limitada aos primeiros 10 dígitos após o prefixo google_. Portanto, não há uma correspondência direta entre os IDs de verificação de mídia ID3 e as chaves no objeto de tags. Isso evita que os pings de verificação de evento sejam enviados antes que o evento ID3 chegue. Para gerar o URL completo de verificação de mídia de um evento de anúncio, anexe o ID completo do evento de anúncio ao valor media_verification_url da resposta de criação de stream.
4. Use eventos de "progresso" para acompanhar se um usuário está em um intervalo de anúncio. Não envie esses eventos para o endpoint de verificação de mídia para evitar um código de erro HTTP. Para outros tipos de evento, anexe o ID da mídia ao URL de verificação de mídia e faça uma solicitação GET para acompanhar a reprodução.
5. Remova o evento de mídia da fila.

endpoint de API

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

Parâmetros de caminho

MEDIA_VERIFICATION_URL	O valor retornado pelo endpoint de registro do stream, no campo media_verification_url: MEDIA_VERIFICATION_URL
AD_MEDIA_ID	O ID completo da mídia do anúncio, conforme aparece nos metadados ID3 do stream: AD_MEDIA_ID

Valores de retorno esperados

HTTP/1.1 204 No Content	Resposta vazia bem-sucedida.
HTTP/1.1 404 Not Found	O ID de verificação de mídia não foi reconhecido.
HTTP/1.1 409 Conflict	O ID de verificação de mídia já foi enviado.

Exemplo de solicitação (cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

Exemplo de resposta

HTTP/1.1 204 No Content

Limitações

Se você usar a API em visualizações da Web, as seguintes limitações serão aplicadas em relação à 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 é transmitido corretamente, o que limita a funcionalidade dos seguintes recursos:
  • Limite de frequência
  • Rotação sequencial de anúncios
  • Segmentação e segmentação por público-alvo