API Linear de inserção de anúncios dinâmicos

Com a API Dynamic Ad Insert, é possível solicitar e acompanhar streams lineares (AO VIVO) da DAI.

Serviço: dai.google.com

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

Método: stream

Métodos
stream	POST /linear/v1/hls/event/{assetKey}/stream Cria um stream de DAI para o ID de evento fornecido.

Solicitação HTTP

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

Cabeçalho da solicitação

Parâmetros
api‑key	string A chave de API fornecida ao criar um stream precisa ser válida para a rede do editor. Em vez de fornecê-la no corpo da solicitação, a chave de API pode ser transmitida no cabeçalho da autorização HTTP com o seguinte formato: Authorization: DCLKDAI key="<api-key>"

Parâmetros de caminho

Parâmetros
assetKey	string ID do evento da transmissão. Observação: a chave do recurso de transmissão é um identificador que também pode ser encontrado na interface do Ad Manager.

Corpo da solicitação

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

Parâmetros
dai-ssb	Opcional	Defina como true para criar um stream de beacon do servidor. O valor padrão é false. O rastreamento do stream padrão é iniciado pelo cliente e recebe um ping do lado do servidor.
Parâmetros de segmentação do DFP	Opcional	Parâmetros de segmentação adicionais.
Substituir os parâmetros do stream	Opcional	Modifique os valores padrão de um parâmetro de criação de stream.
Autenticação HMAC	Opcional	Faça a autenticação usando um token baseado em HMAC.

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta incluirá uma nova Stream. Para streams de beacon do lado do servidor, Stream contém apenas os campos stream_id e stream_manifest.

Open Measurement

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

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

Depois de encontrar um identificador de mídia do anúncio durante a reprodução, faça uma solicitação imediatamente usando o media_verification_url recebido do endpoint stream acima. Essas solicitações não são necessárias para fluxos de beacon do servidor, 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 sobre um evento de verificação de mídia.

Observação: eventos de progresso ID3 não devem receber um ping para esse endpoint. Elas servem para os editores diferenciarem a reprodução dentro e fora de um intervalo de anúncio e não tiverem nenhuma outra finalidade de rastreamento de anúncios. Os editores podem identificar eventos de progresso pesquisando o identificador de mídia no arquivo JSON de metadados e verificando se o campo type está definido como progress.

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 enviados.
• HTTP/1.1 404 Not Found se a solicitação não puder verificar a mídia devido a formatação ou expiração do URL incorreta.
• HTTP/1.1 404 Not Found se uma solicitação de verificação anterior desse ID for bem-sucedida.
• HTTP/1.1 409 Conflict se outra solicitação já estiver enviando pings no momento.

IDs de mídia do anúncio (HLS)

Os identificadores de mídia do anúncio serão codificados em metadados com marcação de tempo HLS usando a chave TXXX, reservada para frames de "informações de texto definidas pelo usuário". O conteúdo do frame não será criptografado e sempre vai começar com o texto "google_".

Todo o conteúdo de texto do frame precisa ser anexado ao URL de verificação do anúncio antes de cada solicitação de verificação.

Método: metadata

O endpoint de metadados em metadata_url retorna informações usadas para criar uma interface do anúncio. 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 de anúncio.

Métodos
metadata	GET /{metadata_url}/{ad-media-id} GET /{metadata_url} Recupera informações de metadados do anúncio.

Observação :é recomendável informar o ID da mídia do anúncio ao endpoint. Caso contrário, use polling_frequency para determinar com que frequência se conectar a esse endpoint.

Solicitação HTTP

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

GET https://{metadata_url}

Corpo da resposta

Se for bem-sucedida, a resposta retornará uma instância de PodMetadata.

Como trabalhar com metadados

Os metadados têm três seções distintas: tags, ads e breaks do anúncio. O ponto de entrada nos dados é a seção tags. A partir daí, navegue pelas tags e encontre a primeira entrada, cujo nome é um prefixo do ID de mídia do anúncio encontrado no stream de vídeo. Por exemplo, você pode ter um ID de mídia do anúncio semelhante a este:

google_1234567890

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

Dados de resposta

Fluxo

O stream é usado para renderizar uma lista de recursos de um stream recém-criado no formato JSON.

Representação JSON
{ "stream_id": string, "stream_manifest": string, "hls_master_playlist": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "polling_frequency": number, }

Campos
stream_id	string O identificador de stream do GAM.
stream_manifest	string O URL do manifesto do stream, usado para recuperar a playlist multivariante em HLS ou o MPD em DASH.
hls_master_playlist	string (DESCONTINUADO) URL da playlist multivariante de HLS. Use "stream_manifest".
media_verification_url	string O URL de verificação de mídia usado como endpoint de 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 mudar 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 de stream.
polling_frequency	number Frequência de pesquisa, em segundos, ao solicitar metadata_url ou Heartbeat_url.

PodMetadata

PodMetadata contém informações de metadados sobre anúncios, intervalos de anúncios 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 dos segmentos de tag indexados por prefixo de tag.
ads	map[string, object(Ad)] Mapa de anúncios indexados por ID do anúncio.
ad_breaks	map[string, object(AdBreak)] Mapa de intervalos de anúncio indexados por ID de 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 no endpoint de verificação de mídia do anúncio.

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 AdBreak 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: pré, intermediário e pós.
duration	number Duração total do anúncio para este 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 de anúncio.

Anúncio

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 ID do intervalo de anúncio deste anúncio.
position	number Posição do anúncio no intervalo de anúncio, 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 opcional do criativo.
creative_ad_id	string ID opcional do anúncio do criativo.
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 de verificação opcionais do Open Measurement que listam os recursos e metadados necessários para executar o código de medição de terceiros e verificar a reprodução de criativos.
slate	boolean Booleano opcional indicando que a entrada atual é barreira.
icons	[object(Icon)] Uma lista de ícones, omitida se estiver vazia.
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 todos os nós de <Extension> no VAST.
companions	[object(Companion)] Complementares opcionais que podem ser exibidos com este anúncio.
interactive_file	object(InteractiveFile) Criativo interativo opcional (SIMID) que deve ser exibido durante a reprodução do anúncio.

Icon

Ícone que 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 clique 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

O wrapper contém informações sobre um anúncio wrapper. Ele não incluirá um ID de transação se ele não existir.

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 anúncio 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 do Open Measurement, o que facilita a visibilidade e a medição da verificação de terceiros. Atualmente, só há suporte para recursos JavaScript. 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 foi transmitida para o 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 o payload do JavaScript.
api_framework	string APIFramework é o nome do framework de vídeo que aplica o código de verificação.
browser_optional	boolean Define se este script pode ser executado fora de um navegador.

TrackingEvent

O TrackingEvent contém URLs que devem receber um ping pelo cliente em determinadas situações.

Representação JSON
{ "event": string, "uri": string, }

Campos
event	string O tipo do evento de rastreamento.
uri	string O evento de rastreamento que receberá o ping.

UniversalAdID

O UniversalAdID é usado para fornecer um identificador de criativo exclusivo que é mantido 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.
id_registry	string Uma string usada para identificar o URL do site de registro em que o ID universal do anúncio do criativo selecionado é catalogado.

Complementar

O complementar contém informações para 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 deste complementar.
creative_type	string O atributo CreativeType no nó <StaticResource> no VAST se for um complementar do tipo "estático".
height	int32 A altura em pixels do complementar.
width	int32 A largura em pixels deste complementar.
resource	string Para complementares estáticos e iframe, esse será o URL a ser carregado e exibido. Para complementares HTML, é o snippet HTML que deve ser mostrado como o complementar.
type	string Tipo do complementar. Ele pode ser estático, iframe ou HTML.
ad_slot_id	string O ID do espaço deste complementar.
api_framework	string O framework da API para esse complemento.
tracking_events	[object(TrackingEvent)] Lista de eventos de rastreamento para este complementar.

InteractiveFile

InteractiveFile contém informações do criativo interativo (ou seja, SIMID) que precisa 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 para o criativo interativo.
type	string O tipo MIME do arquivo fornecido como o recurso.
variable_duration	boolean Se este criativo pode pedir a extensão da duração.
ad_parameters	string O valor do nó <AdParameters> no VAST.