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

A API Dynamic Ad Insertion permite solicitar e acompanhar 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

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

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 concluída, o corpo da resposta conterá um novo objeto Stream.

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 para 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: segmento do conjunto

Solicitação HTTP

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

Parâmetros de caminho

Parâmetros de consulta

Notas de rodapé

1. sd não é obrigatório para segmentos de inicialização. ↩
2. pd não é necessário para eventos com intervalos de anúncio sem duração ativados. ↩

Exemplo

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/ad_break_id/adbreak-2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/pod/2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

Corpo da resposta

Se for bem-sucedido, o corpo da resposta será um segmento de transmissão reproduzível que corresponde ao formato e aos parâmetros especificados na solicitação.

Método: manifesto do pod HLS

Recupera um manifesto de bloco de anúncios HLS de uma transmissão ao vivo que está pronto para ser carregado e reproduzido por um player de vídeo do cliente.

Solicitação HTTP

GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}.m3u8?stream_id={stream_id}&pd={pod_duration}

Parâmetros de caminho

Parâmetros de consulta

Corpo da resposta

Se bem-sucedido, o corpo da resposta será uma playlist multivariante de HLS.

Método: manifesto do pod DASH

Recupera um manifesto de conjunto de anúncios MPEG-DASH de uma transmissão ao vivo que está pronta para ser carregada e reproduzida por um player de vídeo do cliente.

Solicitação HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/stream/{stream_id}/pod/{pod_id}/manifest.mpd?pd={pod_duration}

Parâmetros de caminho

Parâmetros de consulta

Corpo da resposta

Se bem-sucedido, o corpo da resposta será uma playlist mpd MPEG-DASH.

Método: modelo de período de pod 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 de consulta

Corpo da resposta

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

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 transmissões de beacon 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 do URL incorreta.
• 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 da mídia do anúncio

Os identificadores de mídia do anúncio serão codificados em uma faixa de metadados separada: metadados cronometrados para o fluxo de transporte HLS ou emsg para arquivos mp4. Os identificadores de mídia de anúncios sempre começam com a string google_.

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

Método: metadata

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

Solicitação HTTP

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

GET https://{metadata_url}

Corpo da resposta

Se funcionar, a resposta vai retornar uma instância de PodMetadata.

Como analisar 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 de anúncio parecido com 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 de prefixo de mídia de anúncio correto, 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úncios são usados para indexar os objetos breaks.

Dados de resposta

Stream

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

PodMetadata

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

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

PodTemplateResponse

{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}

Í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,
}