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 guia abrange 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 streams em direto 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 impressões 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 em direto	O ID de configuração em direto que especificou quando criou o evento de stream em direto: `LIVE_CONFIG_ID`
Chave do recurso personalizada	A chave do recurso personalizado do Ad Manager gerada durante o processo de criação de uma configuração para um evento de stream em direto com a API Video Stitcher: `CUSTOM_ASSET_KEY`

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 a API de união de vídeos.

Ponto final da API

POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

Parâmetros de caminho

`NETWORK_CODE`	O código de rede do Google Ad Manager 360: `NETWORK_CODE`
`CUSTOM_ASSET_KEY`	O identificador personalizado associou este evento no Google Ad Manager: `CUSTOM_ASSET_KEY`

Parâmetros do corpo com codificação de formulário

Um conjunto opcional de parâmetros de segmentação codificados em formulário.

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`
`polling_frequency`	a frequência recomendada em milissegundos para sondar o `metadata_url`. `POLLING_FREQUENCY`
`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/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

Exemplo de resposta

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

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 o URI de reprodução da sessão

Faça um pedido POST ao ponto final /livesessions da API Video Stitcher para criar uma nova sessão em direto. Em troca, recebe uma resposta JSON com o manifesto da stream para carregar no seu leitor de vídeo.

Ponto final da API

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

Parâmetros de caminho

`PROJECT_NUMBER`	O número do projeto do Google Cloud que usa a API Video Stitcher: `PROJECT_NUMBER`
`LOCATION`	A região do Google Cloud onde a sua configuração em direto foi criada: `LOCATION`

Parâmetro do cabeçalho de autorização

OAUTH_TOKEN

Um token OAuth de curta duração de uma conta de serviço com a função de utilizador do Video Stitcher:

OAUTH_TOKEN

Parâmetros do corpo com código JSON

`liveConfig`	Uma string que contém o seu número do projeto, localização e ID da configuração em direto com o seguinte formato: `projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID`
`adTracking`	Defina como `"CLIENT"` para ativar o acompanhamento do lado do cliente.
`gamSettings`	Um objeto que contém o ID da stream com o seguinte formato: `{"streamId":"STREAM_ID"}`

JSON de resposta

`name`	O nome da sessão em direto, 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. `PLAY_URI`
`liveConfig`	A mesma string `liveConfig` 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/liveSessions

request.json

{
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
  "adTracking": "CLIENT",
  "gamSettings": {
    "streamId": "STREAM_ID"
  }
}

Exemplo de resposta

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
  "playUri": PLAY_URI,
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
  "gamSettings": {
    "streamId": STREAM_ID
  }
}

Depois de receber a resposta, pode ver a stream em direto com anúncios incorporados fazendo referência ao URI de reprodução da sessão do campo playUri do objeto de resposta.

A API Video Stitcher gera um ID da sessão exclusivo para cada pedido, que pode ser obtido na última secção do campo name do objeto de resposta.

Uma sessão inativa expira após 5 minutos. Uma sessão é considerada inativa se não tiverem sido feitas obtenções de manifestos durante um período de tempo.

Sondar novos metadados de AdBreak

A aplicação é responsável por obter metadados para cada intervalo de anúncios, para saber que impressões têm de ser acionadas. Para o fazer, vai definir um temporizador para sondar regularmente as APIs DAI metadata_url para obter novas informações sobre anúncios. O intervalo de sondagem é especificado no campo polling_frequency na resposta de registo da stream.

Em troca, recebe um objeto JSON com os seguintes parâmetros:

`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.

Armazene estes valores após cada sondagem para associar eventos de metadados cronometrados na sua stream de vídeo.

Exemplo de pedido (cURL)

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

Exemplo de resposta

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },
      ...
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/...",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },
      ...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },
      ...
   }
}

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

tvOS

Avançar

Limpar

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 codificação de formulário

JSON de resposta

Exemplo de pedido (cURL)

Exemplo de resposta

Gere o URI de reprodução da sessão

Ponto final da API

Parâmetros de caminho

Parâmetro do cabeçalho de autorização

Parâmetros do corpo com código JSON

JSON de resposta

Exemplo de pedido (cURL)

Exemplo de resposta

Sondar novos metadados de AdBreak

Exemplo de pedido (cURL)

Exemplo de resposta

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