Para ativar a API Video Stitcher para o seu projeto, contacte o seu representante da conta ou o departamento de vendas para saber mais.

Esta página foi traduzida pela API Cloud Translation.

Use uma integração personalizada

Antes de começar

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

Certifique-se de que já concluiu os passos em Integre o Google Ad Manager (GAM) com recursos de VOD anteriormente.

Se o SDK para IMA não estiver disponível para a plataforma pretendida, a sua aplicação tem de chamar as APIs necessárias e acionar as validações de suportes multimédia de anúncios.

Para o fazer, precisa das seguintes informações:

Localização	A região do Google Cloud onde a sua configuração em direto foi criada: `LOCATION`
Número do projeto	O número do projeto do Google Cloud que usa a API Video Stitcher: `PROJECT_NUMBER`
Símbolo do OAuth	Um token OAuth de curta duração de uma conta de serviço com a função de utilizador do Video Stitcher: `OAUTH_TOKEN` Leia mais sobre como criar tokens OAuth de curta duração. Ponto-chave: O token OAuth pode ser reutilizado em vários pedidos, desde que não tenha expirado.
Código de rede	O código de rede do Ad Manager para pedir anúncios: `NETWORK_CODE`
ID da configuração de VOD	O ID da configuração de VOD que especificou quando criou o evento de stream de VOD: `VOD_CONFIG_ID`

Faça um pedido de registo de stream ao Ad Manager

Faça um pedido POST ao ponto final de registo da stream. Em troca, recebe uma resposta JSON com o ID da stream para enviar para o servidor de manipulação do manifesto e os pontos finais da API de publicação de grupos de anúncios associados.

Ponto final da 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 O seu código de rede do Google Ad Manager 360

Parâmetros do corpo com código JSON

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

JSON de resposta

`media_verification_url`	O URL base para enviar pings de eventos de acompanhamento de reprodução. Um URL de validação de multimédia completo é formado anexando um ID do evento de anúncio a este URL base. `MEDIA_VERIFICATION_URL`
`metadata_url`	O URL para pedir metadados de agrupamentos de anúncios. `METADATA_URL`
`stream_id`	A string usada para identificar a sessão de stream atual. `STREAM_ID`
`valid_for`	O tempo restante até a sessão de streaming atual expirar, no formato de `dhms` (dias, horas, minutos e segundos). Por exemplo, `2h0m0.000s` representa uma duração de 2 horas.
`valid_until`	A hora em que a sessão de streaming atual expira, como uma string de data/hora ISO 8601 no formato `yyyy-MM-dd'T'hh:mm:ss.sssssssss[+\|-]hh:mm`.

Exemplo de pedido (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, são devolvidos códigos de erro HTTP padrão sem um corpo de resposta JSON.

Analise a resposta JSON e armazene os valores relevantes.

Gere uma sessão de VOD do Editor de vídeo do Google Cloud

Faça um pedido POST ao ponto final de registo da sessão de VOD. Em troca, recebe uma resposta JSON com o URI do manifesto de stream e os metadados relativos a pausas para anúncios, anúncios e eventos de anúncios.

Ponto final da 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`	O número do seu projeto do Google Cloud.
`LOCATION`	A sua região do Google Cloud.
`NETWORK CODE`	O seu código de rede do Google Ad Manager 360.

Parâmetros do corpo com código JSON

`vodConfig`	Uma string que contém o seu número do projeto, localização e ID de configuração de VOD com o seguinte formato: `projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID`
`adTracking`	Defina como `"CLIENT"` para ativar o acompanhamento do lado do cliente.
`gamSettings`	Um objeto que contém o código da rede e o ID da stream 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 da stream unida, para carregar no leitor de vídeo para reprodução. `SESSION_PLAYBACK_URI`
`adTracking`	O mesmo valor `adTracking` enviado para a API no corpo do pedido.
`vodConfig`	A mesma string `vodConfig` enviada para a API no corpo do pedido.
`gamSettings`	O mesmo objeto `gamSettings` enviado para a API no corpo do pedido.

Exemplo de pedido (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 de receber a resposta, pode ver a stream em direto com anúncios incorporados fazendo referência ao URI do campo playUri do objeto de resposta.

Peça metadados de grupos de anúncios ao Ad Manager

Faça um pedido GET ao metadata_url que recebeu quando registou a sua stream no Ad Manager. Este passo tem de ocorrer depois de receber o manifesto unido do URI de reprodução.

Por sua vez, recebe um objeto JSON que descreve as pausas para anúncios, os anúncios e os eventos de anúncios da stream.

Ponto final da API

GET: METADATA_URL
Host: dai.google.com

JSON de resposta

`tags`	Um conjunto de pares de chave-valor que descrevem eventos de multimédia de anúncios que ocorrem na stream. Cada chave consiste nos primeiros 17 carateres de um ID de multimédia do anúncio que vai aparecer nos metadados ID3 da stream ou, no caso de eventos "progress", no ID de multimédia do anúncio completo. Cada valor é um objeto com as seguintes propriedades: `ad`: o ID do anúncio que contém o evento de conteúdo multimédia do anúncio. `ad_break_id`: O ID da pausa para anúncios que contém o evento multimédia do anúncio. `type`: o tipo de evento de multimé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`: acionado a cada segundo durante a reprodução de um anúncio.
`ads`	Um conjunto de pares de chaves-valores que descrevem os anúncios que vão aparecer no stream. Cada chave é um ID do anúncio. Cada valor é um objeto com as seguintes propriedades: `ad_break_id`: O ID da pausa para anúncios que contém o evento multimédia do anúncio. `position`: a posição do anúncio na pausa para anúncios. Tenha em atenção que o primeiro anúncio num intervalo tem a posição `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 a abrir quando um utilizador interage com o anúncio. `universal_ad_id`: um objeto que representa o ID do anúncio universal, conforme definido no VAST.
`ad_breaks`	Um conjunto de pares de chave-valor que descrevem as pausas de anúncios que ocorrem na stream. Cada chave é um ID de pausa para anúncios. Cada valor é um objeto com as seguintes propriedades: `type`: o tipo de pausa para anúncios. Os valores serão um dos seguintes: `pre`: representa um anúncio de inserção inicial. `mid`: representa um anúncio de inserção intercalar. `post`: representa um anúncio de inserção final. `duration`: A duração da pausa para anúncios em segundos de ponto flutuante. `expected_duration`: A duração esperada do intervalo de anúncios em segundos de vírgula flutuante. `ads`: o número de anúncios contidos na pausa para anúncios.

Exemplo de pedido (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 estes valores para associar a eventos de metadados sincronizados no seu stream de vídeo.

Ouvir eventos ID3 e acompanhar eventos de reprodução

Para verificar se ocorreram eventos específicos numa stream de vídeo, siga estes passos para processar eventos ID3:

Armazene os eventos multimédia numa fila, guardando cada ID de multimédia juntamente com a respetiva data/hora, se forem apresentados pelo leitor.
Em cada atualização de tempo do leitor ou a uma frequência definida (recomendada de 500 ms), verifique a fila de eventos multimédia para ver eventos reproduzidos recentemente comparando as datas/horas dos eventos com o indicador de tempo.
Para eventos de multimédia cuja reprodução confirmou, verifique o tipo pesquisando o ID de multimédia nas etiquetas de pausas publicitárias armazenadas. Tenha em atenção que o objeto ad break tags contém apenas uma versão truncada do ID de multimédia, limitada aos primeiros 10 dígitos após o prefixo google_, pelo que não existe uma correspondência direta entre os IDs de verificação de multimédia ID3 e as chaves no objeto tags. Isto destina-se a impedir o envio de pings de validação de eventos antes da chegada do evento ID3. Para gerar o URL de validação de multimédia completo de um evento de anúncio, anexe o ID do evento de anúncio completo ao valor de media_verification_url da resposta de criação de streams.
Use eventos de "progresso" para acompanhar se um utilizador está numa pausa para anúncio. Não envie estes eventos para o ponto final de validação de multimédia para evitar um código de erro HTTP. Para outros tipos de eventos, anexe o ID de multimédia ao URL de validação de multimédia e faça um pedido GET para acompanhar a reprodução.
Remova o evento multimédia da fila.

Ponto final da API

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

Parâmetros de caminho

`MEDIA_VERIFICATION_URL`	O valor devolvido pelo ponto final de registo de streams, no campo `media_verification_url`: `MEDIA_VERIFICATION_URL`
`AD_MEDIA_ID`	O ID de multimédia do anúncio completo, tal como aparece nos metadados ID3 da stream: `AD_MEDIA_ID`

Valores de retorno esperados

`HTTP/1.1 204 No Content`	Resposta vazia com êxito.
`HTTP/1.1 404 Not Found`	O ID de validação de meios de comunicação não foi reconhecido.
`HTTP/1.1 409 Conflict`	O ID de validação de conteúdo multimédia já foi enviado.

Exemplo de pedido (cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

Exemplo de resposta

HTTP/1.1 204 No Content

Limitações

Se usar a API em visualizações Web, aplicam-se as seguintes limitações relativamente à segmentação:

UserAgent: o parâmetro do agente do utilizador é transmitido como um valor específico do navegador em vez da plataforma subjacente.
rdid, idtype e is_lat: o ID do dispositivo não é transmitido corretamente, o que limita a funcionalidade das seguintes funcionalidades:
- Limite de frequência
- Rotação de anúncios sequencial
- Segmentação e segmentação por público-alvo

Avançar

Vista geral

Use uma integração personalizada Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Faça um pedido de registo de stream ao Ad Manager

Ponto final da API

Parâmetros de caminho

Parâmetros do corpo com código JSON

JSON de resposta

Exemplo de pedido (cURL)

Exemplo de resposta

Gere uma sessão de VOD do Editor de vídeo do Google Cloud

Ponto final da API

Parâmetros de caminho

Parâmetros do corpo com código JSON

JSON de resposta

Exemplo de pedido (cURL)

Exemplo de resposta

Peça metadados de grupos de anúncios ao Ad Manager

Ponto final da API

JSON de resposta

Exemplo de pedido (cURL)

Exemplo de resposta JSON

Ouvir eventos ID3 e acompanhar eventos de reprodução

Ponto final da API

Parâmetros de caminho

Valores de retorno esperados

Exemplo de pedido (cURL)

Exemplo de resposta

Limitações

Use uma integração personalizada