API dinâmica de veiculação de conjunto de Inserção de anúncios dinâmicos

Com a API Dynamic Ad inserção, é possível solicitar e rastrear transmissões ao vivo da DAI.

Serviço: dai.google.com

Todos os URIs são relativos a https://dai.google.com.

Método: stream

Métodos
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Registra uma sessão de transmissão ao vivo de pod de DAI com veiculação.

Solicitação HTTP

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Parâmetros de caminho

Parâmetros
network_code string

O código de rede do Google Ad Manager do editor.

custom_asset_key string

É o identificador personalizado associado a este evento no Google Ad Manager.

Corpo da solicitação

O corpo da solicitação é do tipo application/x-www-form-urlencoded e contém a parâmetros a seguir:

Parâmetros
Parâmetros de segmentação do DFP Opcional Outros parâmetros de segmentação.
Substituir parâmetros de stream Opcional Substituir os valores padrão de um parâmetro de criação de stream.
Autenticação HMAC Opcional Autentique usando um token baseado em HMAC.

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta incluirá um novo objeto Stream.

Open Measurement

A API DAI contém informações para a verificação do Open Measurement no Verifications. Este campo contém um ou mais Elementos Verification que listam os recursos e metadados necessários para execução código de medição de terceiros para verificar a reprodução de criativos. Somente JavaScriptResource é compatível. Para mais informações, consulte a IAB Tech Lab e os Especificação VAST 4.1.

Método: segmento do conjunto

Métodos
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Cria um stream da DAI para o ID de evento especificado.

Solicitação HTTP

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Parâmetros de caminho

Parâmetros
network_code string

O código de rede do Google Ad Manager do editor.

custom_asset_key string

É o identificador personalizado associado a este evento no Google Ad Manager.

pod_id integer

É o identificador numérico do intervalo de anúncio atual. Os IDs de conjuntos de anúncios são atribuídas de forma incremental para cada evento, começando em 1.
profile_name string

O nome do(s) solicitado(s) perfil de codificação da DAI do Google Ad Manager. O perfil de codificação precisa ser um dos perfis configurados para o evento selecionado.

segment_number integer

O índice do segmento solicitado dentro do conjunto de anúncios atual, começando em zero.
segment_format string

A extensão de arquivo associada ao formato de segmento solicitado. Extensões aceitas: ts, mp4, vtt, aac, ac3 ou eac3.

Parâmetros de consulta

Parâmetros
stream_id required string

O código de stream da sessão do usuário atual. Esse valor é retornado pelo uma solicitação bem-sucedida para o endpoint stream.
sd required1 integer

A duração do segmento solicitado, em milissegundos.
so opcional

O deslocamento do segmento solicitado dentro do conjunto de anúncios, em milissegundos. Se você omitir o parâmetro so, ele será calculado da seguinte forma: multiplicando a duração do segmento pelo número do segmento.
pd obrigatório2 integer

É a duração do conjunto de anúncios, em milissegundos.
auth-token required string

Uma assinatura assinada e codificada por URL Token HMAC para o conjunto de anúncios atual.
last opcional boolean

Indica o último segmento no intervalo de anúncio. Omitir este parâmetro para todos outros segmentos.
scte35 opcional string

SCTE-35signal codificado em Base64 para este intervalo de anúncio.
cust_params opcional string

É um conjunto de pares de chave-valor usado para a segmentação de campanhas do Ad Manager. Esses precisam ser representados como uma string de consulta codificada pelo URL.

Exemplo:
Parâmetros
  • seção = sports
  • página = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Notas de rodapé

  1. O sd não é necessário para segmentos de inicialização. ↩
  2. pd não é necessário para eventos com eventos de anúncio sem duração estão ativadas. ↩

Corpo da resposta

Se bem-sucedido, o corpo da resposta será um segmento de stream reproduzível correspondente ao o formato e os parâmetros especificados na solicitação.

Método: modelo de período de conjunto DASH

Métodos
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Solicita um modelo de período DASH do Google Ad Manager. Este modelo contém macros que precisam ser preenchidas com os parâmetros do stream. Uma vez essas macros forem preenchidas, o modelo se tornará seu período de intervalo de anúncio e pode ser integrado ao manifesto DASH.

Solicitação HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Parâmetros de caminho

Parâmetros
network_code string

O código de rede do Google Ad Manager do editor.

custom_asset_key string

É o identificador personalizado associado a este evento no Google Ad Manager.

Parâmetros de consulta

Parâmetros
stream_id required string

O código de stream da sessão do usuário atual. Esse valor é retornado pelo uma solicitação bem-sucedida para o endpoint stream.

Corpo da resposta

Se bem-sucedido, o corpo da resposta conterá uma nova Objeto PodTemplateResponse.

Método: verificação de mídia

Após encontrar um identificador de mídia do anúncio durante a reprodução, faça imediatamente uma solicitação usando o media_verification_url obtido do stream endpoint, acima. Essas solicitações não são necessárias para beacon do servidor streams, em que o servidor inicia a verificação de mídia.

As solicitações para o endpoint media verification são idempotentes.

Métodos
media verification GET /{media_verification_url}/{ad_media_id}

Notifica a API de um evento de verificação de mídia.

Solicitação HTTP

GET https://{media-verification-url}/{ad-media-id}

Corpo da resposta

media verification retorna as seguintes respostas:

  • HTTP/1.1 204 No Content se a verificação de mídia for bem-sucedida e todos os pings forem enviada.
  • HTTP/1.1 404 Not Found se a solicitação não puder verificar a mídia devido a a formatação ou a expiração do URL está incorreta;
  • HTTP/1.1 404 Not Found se uma solicitação de verificação anterior para este documento de identificação bem-sucedido.
  • HTTP/1.1 409 Conflict se outra solicitação já estiver enviando pings nesta tempo de resposta.

IDs da mídia do anúncio

Os identificadores de mídia do anúncio serão codificados em uma faixa de metadados separada (com marcação de tempo) metadados para fluxo de transporte HLS ou emsg para arquivos mp4. Identificadores de mídia do anúncio sempre vai começar com a string google_.

Todo o conteúdo de texto da entrada de metadados deve ser anexado ao anúncio URL de verificação antes de fazer cada solicitação de verificação de anúncio.

Método: metadata

O endpoint de metadados em metadata_url retorna as informações usadas para criar um anúncio. de ML pela IU. O endpoint de metadados não está disponível para streams de beacon do servidor, em que o servidor é responsável por iniciar a verificação da mídia do anúncio.

Métodos
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

Recupera informações de metadados do anúncio.

Solicitação HTTP

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

Corpo da resposta

Se bem-sucedido, a resposta retorna uma instância de PodMetadata

Como analisar metadados

Os metadados têm três seções distintas: tags, ads e anúncio breaks. A entrada aos dados é a seção tags. A partir daí, itere as tags e encontre a primeira entrada cujo nome seja um prefixo do ID da mídia do anúncio encontrado no stream de vídeo. Por exemplo, pode ter um ID de mídia do anúncio que se parece com:

google_1234567890

Em seguida, você encontrará um objeto de tag chamado google_12345. Nesse caso, ele corresponde ao seu ID da mídia do anúncio. Quando encontrar o objeto correto de prefixo de mídia do anúncio, você poderá procurar IDs de anúncio, IDs de intervalo de anúncio e o tipo de evento. Os IDs dos anúncios são usados para indexar Os objetos ads e os IDs de intervalos de anúncio são usados para indexar os objetos breaks.

Dados de resposta

Stream

O stream é usado para renderizar uma lista de recursos para um stream recém-criado JSON.
Representação JSON
{
  "stream_id": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
Campos
stream_id string

O identificador de stream do GAM.
media_verification_url string

O URL de verificação de mídia usado como endpoint base para rastrear eventos de reprodução.
metadata_url string

URL de metadados usado para pesquisar informações periódicas sobre os próximos eventos de anúncios de streaming.
session_update_url string

O URL de atualização da sessão usado para atualizar os parâmetros de segmentação desse stream. Os valores originais dos parâmetros de segmentação são capturados durante a solicitação inicial de criação do stream.
heartbeat_url string

O URL do sinal de funcionamento, usado para manter ativo o stream de beacon do lado do servidor Ele deve receber um ping a cada {PollingFrequency} segundos. Preenchido para fluxos de beacon do lado do servidor.
polling_frequency number

A frequência de pesquisa, em segundos, ao solicitar metadata_url ou heartbeat_url.
pod_manifest_url string

O modelo de URL do manifesto do pod é usado para gerar o URL e recuperar o manifesto do pod de um fluxo. correspondente ao URL da playlist multivariante em HLS ou à MPD no DASH. Preenchido para eventos de transmissão ao vivo do tipo Inserção de anúncios dinâmicos POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

O formato do manifesto é o formato extraído de pod_manifest_url, traço ou hls.

PodMetadata

O PodMetadata contém informações de metadados sobre anúncios, intervalos de anúncio e tags de ID de mídia.
Representação JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
Campos
tags map[string, object(TagSegment)]

Mapa de segmentos de tag indexados por prefixo de tag.
ads map[string, object(Ad)]

Mapa de anúncios indexados pelo ID do anúncio.
ad_breaks map[string, object(AdBreak)]

Mapa de intervalos de anúncio indexados pelo ID do intervalo de anúncio.

TagSegment

TagSegment contém uma referência a um anúncio, seu intervalo de anúncio e tipo de evento. TagSegment com type="progress" não pode receber um ping na mídia do anúncio endpoint de verificação.
Representação JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Campos
ad string

O ID do anúncio desta tag.
ad_break_id string

É o ID do intervalo de anúncio desta tag.
type string

O tipo de evento desta tag.

AdBreak

O intervalo de anúncio descreve um único intervalo de anúncio no stream. Ele contém uma duração, um tipo (meio/pré/pós) e o número de anúncios.
Representação JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Campos
type string

Os tipos de intervalo válidos são: antes, no meio e após.
duration number

Duração total do anúncio para esse intervalo de anúncio, em segundos.
expected_duration number

Duração esperada do intervalo de anúncio (em segundos), incluindo todos os anúncios e qualquer barreira.
ads number

Número de anúncios no intervalo.
O anúncio descreve um anúncio no stream.
Representação JSON
{
  "ad_break_id": string,
  "position": number,
  "duration": number,
  "title": string,
  "description": string,
  "advertiser": string,
  "ad_system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
  "clickthrough_url": string,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
Campos
ad_break_id string

É o ID do intervalo de anúncio deste anúncio.
position number

Posição deste anúncio no intervalo, começando em 1.
duration number

Duração do anúncio, em segundos.
title string

Título opcional do anúncio.
description string

Descrição opcional do anúncio.
advertiser string

Identificador opcional do anunciante.
ad_system string

Sistema de anúncios opcional.
ad_id string

ID do anúncio opcional.
creative_id string

ID do criativo opcional.
creative_ad_id string

ID do anúncio do criativo opcional.
deal_id string

ID da transação opcional.
clickthrough_url string

URL de clique opcional.
click_tracking_urls string

URLs de rastreamento de cliques opcionais.
verifications [object(Verification)]

Entradas opcionais de verificação do Open Measurement que listam os recursos e os metadados necessários para executar o código de medição de terceiros a fim de verificar a reprodução de criativos.
slate boolean

Booleano opcional que indica que a entrada atual é barreira.
icons [object(Icon)]

Uma lista de ícones, omitidos se estiverem vazios.
wrappers [object(Wrapper)]

Uma lista de wrappers, omitida se estiver vazia.
universal_ad_id object(UniversalAdID)

ID universal do anúncio opcional.
extensions string

Lista opcional de todas as <Extension> no VAST.
companions [object(Companion)]

Complementares opcionais que podem ser mostrados com este anúncio.
interactive_file object(InteractiveFile)

Criativo interativo opcional (SIMID) que deve ser exibido durante a reprodução do anúncio.

PodTemplateResponse

PodTemplateResponse representa o payload JSON retornado a um VTP para agrupamento de pods.
Representação JSON
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
Campos
dash_period_template string

O DashPeriodTemplate é o modelo XML para o período que precisa ser preenchido com os dados apropriados antes do agrupamento.
segment_duration_ms int64

SegmentDurationMS é a duração dos segmentos do período em milissegundos.

Ícone

O ícone contém informações sobre um ícone VAST.
Representação JSON
{
  "click_data": object(ClickData),
  "creative_type": string,
  "click_fallback_images": [object(FallbackImage)],
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "x_position": string,
  "y_position": string,
  "program": string,
  "alt_text": string,
}
Campos
click_data object(ClickData)

creative_type string

click_fallback_images [object(FallbackImage)]

height int32

width int32

resource string

type string

x_position string

y_position string

program string

alt_text string

ClickData

ClickData contém informações sobre o click-through de um ícone.
Representação JSON
{
  "url": string,
}
Campos
url string

FallbackImage

FallbackImage contém informações sobre uma imagem substituta VAST.
Representação JSON
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
Campos
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

Wrapper contém informações sobre um anúncio wrapper. Ele não inclui um ID da transação, se não houver.
Representação JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Campos
system string

Identificador do sistema de anúncios.
ad_id string

ID do anúncio usado para o anúncio wrapper.
creative_id string

ID do criativo usado para o anúncio wrapper.
creative_ad_id string

ID do criativo usado para o anúncio wrapper.
deal_id string

ID da transação opcional para o anúncio wrapper.

Verificação

A verificação contém informações para o Open Measurement, que facilita medição de visibilidade e verificação de terceiros. Atualmente, apenas recursos JavaScript são compatíveis. Consulte https://iabtechlab.com/standards/open-measurement-sdk/
Representação JSON
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
Campos
vendor string

O fornecedor de verificação.
java_script_resources [object(JavaScriptResource)]

Lista de recursos JavaScript para a verificação.
tracking_events [object(TrackingEvent)]

Lista de eventos de rastreamento para a verificação.
parameters string

Uma string opaca transmitida ao código de verificação de inicialização.

JavaScriptResource

JavaScriptResource contém informações para verificação via JavaScript.
Representação JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
Campos
script_url string

URI para payload JavaScript.
api_framework string

APIFramework é o nome do framework de vídeo que reproduz código de verificação.
browser_optional boolean

Se esse script pode ser executado fora de uma navegador.

TrackingEvent

O TrackingEvent contém URLs que devem receber um ping pelo cliente em determinados em diferentes situações.
Representação JSON
{
  "event": string,
  "uri": string,
}
Campos
event string

O tipo do evento de rastreamento.
uri string

O evento de acompanhamento que receberá um ping.

UniversalAdID

O UniversalAdID é usado para fornecer um identificador de criativo exclusivo que é mantidos em todos os sistemas de anúncios.
Representação JSON
{
  "id_value": string,
  "id_registry": string,
}
Campos
id_value string

O ID universal do anúncio do criativo selecionado para o anúncio.
id_registry string

Uma string usada para identificar o URL do site de registro onde o o ID universal do anúncio do criativo selecionado é catalogado.

Complementar

O companion contém informações para os anúncios complementares que podem ser exibidos junto com o anúncio.
Representação JSON
{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "ad_slot_id": string,
  "api_framework": string,
  "tracking_events": [object(TrackingEvent)],
}
Campos
click_data object(ClickData)

Os dados de clique do complementar.
creative_type string

O atributo CreativeType no <StaticResource> no VAST se esse é um complemento do tipo estático.
height int32

A altura em pixels do complementar.
width int32

A largura em pixels desse complementar.
resource string

Para complementares estáticos e iframe, esse será o URL a ser carregado e exibidos. Para complementares HTML, este será o snippet HTML que deve será exibido como complementar.
type string

Tipo do complementar. Ele pode ser estático, iframe ou HTML.
ad_slot_id string

O ID do espaço para este complementar.
api_framework string

O framework da API deste complemento.
tracking_events [object(TrackingEvent)]

Lista de eventos de rastreamento para este complementar.

InteractiveFile

InteractiveFile contém informações para o criativo interativo (por exemplo, SIMID). que deve ser exibido durante a reprodução do anúncio.
Representação JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Campos
resource string

É o URL do criativo interativo.
type string

O tipo MIME do arquivo fornecido como o recurso.
variable_duration boolean

Define se o criativo pode pedir uma extensão de duração.
ad_parameters string

O valor do parâmetro <AdParameters> no VAST.