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

A API Inserção de anúncios dinâmicos permite solicitar e monitorar streams lineares (AO VIVO) da DAI.

Serviço: dai.google.com

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

Método: stream

Solicitação HTTP

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

Cabeçalho da solicitação

Authorization: DCLKDAI key="<api-key>"

Parâmetros de caminho

Corpo da solicitação

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

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta vai conter um novo Stream. Para fluxos de beacon do lado do servidor, esse 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 terceirizada e verificar a reprodução do criativo. 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 de anúncio durante a reprodução, faça imediatamente uma solicitação usando o media_verification_url obtido do endpoint stream. Essas solicitações não são necessárias para streams de beaconing do lado do servidor, em que o servidor inicia a verificação de mídia.

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

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 foi concluída.
• HTTP/1.1 409 Conflict se outra solicitação já estiver enviando pings no momento.

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

Os identificadores de mídia de anúncios serão codificados em metadados temporizados 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 começará com o texto "google_".

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

Método: metadados

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

Solicitação HTTP

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

GET https://{metadata_url}

Parâmetros de consulta

Corpo da resposta

Se a solicitação for bem-sucedida, a resposta vai 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 dos dados é a seção tags. Em seguida, itere pelas 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, você pode ter um ID de mídia de anúncio como este:

google_1234567890

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

Dados de resposta

Stream

{
  "stream_id": string,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}

PodMetadata

{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}

TagSegment

{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}

AdBreak

{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}

Anúncio

{
  "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),
}

Ícone

{
  "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

{
  "url": string,
}

FallbackImage

{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}

Wrapper

{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}

Verificação

{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}

JavaScriptResource

{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}

TrackingEvent

{
  "event": string,
  "uri": string,
}

UniversalAdID

{
  "id_value": string,
  "id_registry": string,
}

Companion

{
  "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)],
}

InteractiveFile

{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}