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 Integrar o Google Ad Manager (GAM) a recursos de VOD de antemão.

Observação :é altamente recomendável usar o SDK de DAI do IMA nas plataformas em que ele tem suporte.

Se o SDK do IMA não estiver disponível para a plataforma pretendida, o aplicativo precisará chamar as APIs necessárias e acionar 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 Leia mais sobre criação de 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 de rede	O código de rede do Ad Manager para solicitar anúncios: NETWORK_CODE
ID de configuração de 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 do stream. 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 dar um ping em eventos de rastreamento de reprodução. Um URL de verificação de mídia completo é formado pela adição de um ID de evento do anúncio a esse URL base. MEDIA_VERIFICATION_URL
metadata_url	O URL para solicitar metadados do bloco 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é 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 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 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 são alterados.

Gerar uma sessão VOD do integrador de vídeos do Cloud

Faça uma solicitação POST para o endpoint de registro da sessão de VOD. Em troca, você receba uma resposta JSON contendo o URI do manifesto de fluxo e os metadados sobre intervalos de anúncios, 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 location e ID de configuração de VOD com o 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 stream id com o seguinte formato: { "networkCode":"NETWORK_CODE", "streamId":"STREAM_ID" }

JSON de resposta

name	O nome da sessão de VOD que contém o ID da sessão.
playUri	O URI do manifesto de fluxo agrupado, a ser carregado 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 à API na solicitação corpo
gamSettings	O mesmo objeto gamSettings enviado à API na solicitação corpo

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á assistir a transmissão ao vivo com o anúncio ao fazer 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 deve ocorrer depois que você receber manifesto integrado do URI de reprodução.

Em troca, você recebe um objeto JSON que descreve os intervalos de anúncios, anúncios e eventos de anúncios 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úncios 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 terminou. progress: é disparado a cada segundo enquanto um anúncio é 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úncios que contém o evento de mídia do anúncio. position: a posição do anúncio no intervalo. 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 em o 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 universal. ID do anúncio, conforme definido no VAST.
ad_breaks	Um conjunto de pares de chave-valor descrevendo os intervalos de anúncio que vão ocorrer no fluxo. Cada chave é um ID de intervalo de anúncios. Cada valor é um 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 anúncio em segundos de ponto flutuante. ads: o número de anúncios contidos no intervalo.

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 com marcação de tempo no seu vídeo riacho.

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. Armazenar os eventos de mídia em uma fila, salvando cada ID de mídia junto com os respectivos o carimbo de data/hora, se for exibido pelo jogador.
2. Em cada atualização do player ou em uma frequência definida (500 ms recomendado), verifique a fila de eventos de mídia para ver os eventos reproduzidos recentemente por comparando os carimbos de data/hora dos eventos com o marcador.
3. Para eventos de mídia que você confirmou que foram reproduzidos, verifique o tipo pesquisando. 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 ao 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 de verificação e fazer uma solicitação GET para rastrear 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:

• User-Agent: 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 de anúncios sequencial
  • Segmentação e segmentação por público-alvo