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

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

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 da DAI para o ID de evento especificado.

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 passada no cabeçalho de autorização HTTP com o seguinte formato: Authorization: DCLKDAI key="<api-key>"

Parâmetros de caminho

Parâmetros
assetKey	string O ID de evento do stream. Observação: a chave de recurso de stream é 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 lado do servidor. O valor padrão é false. O rastreamento do stream padrão é iniciado pelo cliente e recebe um ping no lado do servidor.
Parâmetros de segmentação do DFP	Opcional	Outros parâmetros de segmentação.
Substituir parâmetros de 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 bem-sucedido, o corpo da resposta incluirá um novo Stream. Para streams de beacon do lado do servidor, este Stream contém apenas os campos stream_id e stream_manifest.

Open Measurement

A API DAI contém informações para 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 a fim de verificar a reprodução de criativos. Somente JavaScriptResource é aceito. 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 imediatamente uma solicitação usando o media_verification_url obtido 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 de um evento de verificação de mídia.

Observação: os eventos de progresso ID3 não podem receber um ping nesse endpoint. Eles servem para os editores diferenciarem a reprodução dentro e fora de um intervalo de anúncio e não têm 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 à formatação ou à expiração incorreta do URL.
• HTTP/1.1 404 Not Found se uma solicitação de verificação anterior para esse ID tiver sido 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 do texto do frame precisa ser anexado ao URL de verificação de anúncios antes de você fazer 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 do anúncio.

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

Observação :recomendamos que você informe o ID da mídia do anúncio ao endpoint. Caso contrário, use polling_frequency para determinar a frequência de conexão com esse endpoint.

Solicitação HTTP

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

GET https://{metadata_url}

Corpo da resposta

Se 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 anúncio breaks. O ponto de entrada nos dados é a seção tags. Depois, itere as tags e encontre a primeira entrada cujo nome seja 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ê encontrará 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 de prefixo de mídia do anúncio, é possível procurar IDs de anúncios, IDs de intervalos de anúncio e o tipo de evento. Os IDs de anúncio são entã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

Fluxo

O stream é usado para renderizar uma lista de recursos para 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 HLS. Use "stream_manifest".
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.
polling_frequency	number A frequência de pesquisa, em segundos, ao solicitar metadata_url de ou Heartbeat_url.

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 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. O TagSegment com type="progress" não deve 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 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/pre/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 em um intervalo.

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 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 do anunciante opcional.
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 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 do criativo.
slate	boolean Booleano opcional que indica que a entrada atual é slate.
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 todos os nós <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.

Icon

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 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 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 facilitam a medição da verificação e visibilidade 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 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 payload JavaScript.
api_framework	string APIFramework é o nome do framework de vídeo que executa 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 precisam 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 acompanhamento que receberá um 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 para o anúncio.
id_registry	string Uma string usada para identificar o URL do site de registro em que o ID do anúncio universal do criativo selecionado está 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 cliques do anúncio 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 do complementar.
resource	string Para complementares estáticos e iframe, esse será o URL a ser carregado e exibido. Para complementares HTML, este será 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 deste complemento.
tracking_events	[object(TrackingEvent)] Lista de eventos de rastreamento deste complementar.

InteractiveFile

InteractiveFile contém informações para o criativo interativo (por exemplo, SIMID) que precisam ser mostradas 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 recurso.
variable_duration	boolean Define se este criativo pode pedir uma extensão de duração.
ad_parameters	string O valor do nó <AdParameters> no VAST.