Interfejs API do dynamicznego wstawiania reklam (DAI) umożliwia dostęp do strumieni generujących przychody, gdy pakiet IMA SDK nie jest obsługiwany (np. w przypadku telewizorów smart TV). Pakiet IMA jest wymagany na platformach, na których jest dostępny. Interfejs API obsługuje wszystkie istniejące funkcje DAI, ale wymagają one implementacji przez wydawcę.
Wymagania dotyczące korzystania z interfejsu API
Wydawca, który korzysta z interfejsu API, musi zaimplementować te funkcje:
- Uzyskiwanie dostępu do strumienia DAI przez punkt końcowy HTTP oraz przetwarzanie odpowiedzi w formacie JSON.
- Tworzenie parametrów interfejsu API i par klucz-wartość kierowania.
- Wdrażanie elementów wpływających na wrażenia użytkownika (np. elementów do kliknięcia lub ikon).
- Odsłuchiwanie zdarzeń ID3 w odtwarzaczu w celu zaimplementowania elementów sterujących odtwarzacza i śledzenia reklam lub pomiaru ich skuteczności w przypadku linearnych transmisji na żywo i VOD.
- Wdrażanie funkcji przewijania, cofania do przerwy na reklamę i tworzenia zakładek.
- Wybór formatu strumieniowego przesyłania danych: HLS lub DASH.
Z informacji poniżej dowiesz się, jak przesyłać żądania dotyczące strumieni i przetwarzać je w interfejsie API w przypadku wideo na żądanie lub linearnych transmisji na żywo.
Wideo na żądanie (VOD)
Interfejs API do VOD funkcjonuje według prostego schematu – od utworzenia strumienia do weryfikacji odtwarzania reklamy:
-
Zgłoś żądanie strumienia z HTTP POST, używając identyfikatora źródła treści (
cmsid) i identyfikatora filmu (vid) z kluczem interfejsu API lub tokenem HMAC oraz parametrów kierowania reklamy.https://dai.google.com/ondemand/v1/hls/content/<identyfikator_treści>/vid/<identyfikator_filmu>/stream -
Przetwórz odpowiedzi na plik manifestu dotyczącego odtwarzania treści, napisy, przerwę na reklamę i informacje o czasie wyświetlania treści.
{"content_duration": 123.451,"stream_manifest": "https://dai.google.com/.../master.m3u8","media_verification_url": "https://dai.google.com/.../media/","stream_id": "9ca0c62a-3291-4f95-986f-d1721f8b96f0","total_duration": 163.451,"valid_for": "8h0m0s","valid_until": "2018-05-16T23:21:16.558053292-07:00","ad_breaks": [...]} -
W przypadku każdej przerwy na reklamę przetwarzaj szczegóły dotyczące pojedynczej reklamy związane z jej elementami, takie jak klikalność, elementy towarzyszące i informacje na temat czasu trwania przerwy na reklamę na potrzeby renderowania UI.
{"clickthrough_url": "https://dai.google.com/.../videoclick/1835622921898938400","description": "Example pre-roll ad","duration": 10,"seq": 1,"title": "Example pre-roll"} -
W przypadku każdej reklamy aktywuj parametr
media_verification_url, dodając wartość ID3 z odtwarzania multimediów.https://dai.google.com/view/p/service/vod/stream/3647080d-c223-442e-a364-c456ee712ece/loc/CBF/network/124319096/content/2474148/vid/bbb-clear/media/
Zdarzenia postępu służą do rozróżniania odtwarzania w ramach przerwy na reklamę i poza nią. Nie służą one do innych celów związanych ze śledzeniem reklam.
Zdarzenia postępu możesz zidentyfikować, znajdując identyfikator treści multimedialnych w pliku metadanych JSON i sprawdzając, czy pole type ma wartość progress. Zdarzenia typu „Postęp ID3” mogą służyć między innymi do blokowania elementów sterujących odtwarzaniem filmu.
Strumienie linearnej transmisji na żywo
Interfejs API linearnej transmisji na żywo funkcjonuje według prostego schematu – od utworzenia strumienia do weryfikacji odtwarzania reklamy:
-
Zgłoś żądanie strumienia z HTTP POST, używając identyfikatora zdarzenia z kluczem interfejsu API lub tokenem HMAC oraz parametrów kierowania reklamy.
https://dai.google.com/linear/v1/hls/event/<identyfikator_zdarzenia>/stream
https://dai.google.com/linear/v1/dash/event/<identyfikator_zdarzenia>/stream -
Przetwórz odpowiedzi na plik manifestu dotyczącego odtwarzania treści, napisy, przerwę na reklamę i informacje o czasie wyświetlania treści.
{"stream_manifest": "https://dai.google.com/linear/.../master.m3u8","media_verification_url": "https://dai.google.com/linear/.../media/","metadata_url": "https://dai.google.com/linear/…/metadata","polling_frequency": 10,"stream_id": "793bf10c-2323-404d-b23b-0a529d96e651:MRN",} -
Zgłoś żądanie metadanych reklamy z częstotliwością odpytywania lub dla każdego identyfikatora multimediów reklamy ID3, dołączając identyfikator multimediów reklamy do adresu URL metadanych w parametrze zapytania.
{"ad_ breaks": {"0001127859": {"ads": 3,"duration": 30,"type": "mid"}},"ads": {"0001127859_ad2": {"ad_break_id": "0001127859","ad_id": "39135088","ad_system": "GDFP","clickthrough_url": "http://pubads.g.doubleclick.net/pcs/click?...","creative_id": "103990016608","description": "Example linear 10s ad","duration": 10,"position": 2,"title": "Example linear ad"}},"tags": {"google_0028792773": {"ad": "0001127859_ad2","ad_break_id": "0001127859","type": "firstquartile"}, ...}} -
W przypadku każdej reklamy aktywuj parametr
media_verification_url, dodając wartość ID3 z odtwarzania multimediów.https://dai.google.com/view/p/service/linear/stream/f0b8970b-cacb-4a9f-83ee-2ef29db47129:CBF2/loc/CBF2/network/51636543/event/sN_IYUG8STe1ZzhIIE_ksA/media/
Zdarzenia postępu służą do rozróżniania odtwarzania w ramach przerwy na reklamę i poza nią. Nie służą one do innych celów związanych ze śledzeniem reklam.
Zdarzenia postępu możesz zidentyfikować, znajdując identyfikator treści multimedialnych w pliku metadanych JSON i sprawdzając, czy pole type ma wartość progress. Zdarzenia typu „Postęp ID3” mogą służyć między innymi do blokowania elementów sterujących odtwarzaniem filmu.
Wykrywanie momentu rozpoczęcia/zakończenia przerwy na reklamę za pomocą interfejsu DAI API
Interfejs DAI wstawia metadane ID3 dotyczące zdarzeń kwartyli (np. Start, Pierwszy kwartyl, Połowa, Trzeci kwartyl i Zakończone) do segmentów reklam i zdarzenia postępu (co sekundę) do segmentów reklam i pakietów. Przy pierwszym wystąpieniu takiego tagu ID3 można wywołać zdarzenie „rozpoczęcia przerwy na reklamę”. Jeśli później przez jakiś czas nie pojawią się żadne takie tagi ID3 (np. przez 2,5 sekundy), można wywołać „zakończenie przerwy na reklamę”. Tagi ID3 wstawione przez interfejs DAI można rozpoznać po prefiksie „google_” i obecności w pliku JSON metadanych.
Dynamiczne aktualizowanie kierowania lub par klucz-wartość w strumieniu użytkownika
Parametr session_update_url pozwala zastąpić wszystkie parametry tagu reklamy używane w żądaniach nadchodzących reklam w transmisji na żywo (podobnie jak replaceAdTagParameters). Jest to przydatne, gdy informacje o kierowaniu trzeba zaktualizować na poziomie poszczególnych programów i użytkowników (np. w przypadku wydarzeń sportowych na żywo, na które kierowanie może nie być znane z wyprzedzeniem).