Rozhraní API pro dynamické vkládání reklam (DAI) umožňuje přístup ke zpeněženým streamům, u kterých není podporována sada IMA SDK (například chytré televize). Na platformách, kde je k dispozici sada IMA, je vyžadována tato sada. Rozhraní API podporuje všechny stávající funkce DAI, vyžadují však implementaci na straně majitele obsahu.
Požadavky při používání rozhraní API
V případě použití rozhraní API je na straně majitele obsahu potřeba implementovat následující funkce:
- Přístup ke streamu DAI prostřednictvím koncového bodu HTTP a zpracování odpovědí JSON
- Vygenerování parametrů rozhraní API a párů klíč–hodnota cílení
- Implementace prvků a událostí uživatelského prostředí (například prokliků a ikon)
- Naslouchání událostem ID3 v přehrávači za účelem implementace ovládacích prvků přehrávače a měření reklam pro lineární živé vysílání i video na vyžádání (VOD)
- Implementace scrubbingu, snapbacků a záložek
- Výběr formátů streamování: HLS nebo DASH
Níže uvádíme, jak prostřednictvím rozhraní API požádat o streamy pro video na vyžádání nebo pro lineární živé vysílání a jak je zpracovat.
Video na vyžádání (VOD)
Rozhraní VOD API má jednoduchý životní cyklus od vytvoření streamu po ověření přehrání reklamy:
-
Požádejte o stream pomocí požadavku HTTP POST s ID zdroje obsahu (
cmsid), ID videa (vid), klíčem API nebo tokenem HMAC a parametry cílení reklam.https://dai.google.com/ondemand/v1/hls/content/<contentId>/vid/<vid>/stream -
Zpracujte manifest přehrávání obsahu, titulky a informace o časování reklamních přestávek a obsahu.
{"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": [...]} -
Pro každou reklamní přestávku zpracujte podrobnosti o jednotlivých reklamách pro prvky reklamy, jako jsou informace o prokliku, doprovodných reklamách a trvání reklamních přestávek k vykreslení v uživatelském rozhraní.
{"clickthrough_url": "https://dai.google.com/.../videoclick/1835622921898938400","description": "Example pre-roll ad","duration": 10,"seq": 1,"title": "Example pre-roll"} -
U každé reklamy aktivujte pravidlo
media_verification_urls připojenou hodnotou ID3 z přehrávání reklamního média.https://dai.google.com/view/p/service/vod/stream/3647080d-c223-442e-a364-c456ee712ece/loc/CBF/network/124319096/content/2474148/vid/bbb-clear/media/
Události průběhu (Progress) umožňují odlišit přehrávání během reklamní přestávky od přehrávání mimo ni. K žádným jiným účelům při měření reklam neslouží.
Události průběhu můžete identifikovat tak, že v souboru JSON s metadaty vyhledáte identifikátor média a ověříte, zda je pole type nastavené na hodnotu progress. Událost progress ID3 lze použít například k zablokování ovládacích prvků videa.
Streamy lineárního živého vysílání
Rozhraní API lineárního streamu používá jednoduchý životní cyklus od vytvoření streamu až po ověření přehrání reklamy:
-
Požádejte o stream pomocí požadavku HTTP POST s ID události, klíčem API nebo tokenem HMAC a parametry cílení reklam.
https://dai.google.com/linear/v1/hls/event/<eventid>/stream
https://dai.google.com/linear/v1/dash/event/<eventid>/stream -
Zpracujte manifest přehrávání obsahu, titulky a informace o časování reklamních přestávek a obsahu.
{"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",} -
Požádejte o metadata reklamy (buď s dotazovací frekvencí, nebo pro každé ID média reklamy ID3). K adrese URL metadat přidejte parametr s ID reklamního média.
{"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"}, ...}} -
U každé reklamy aktivujte odešlete požadavek na adresu
media_verification_urls připojenou hodnotou ID3 z přehrávání reklamního média.https://dai.google.com/view/p/service/linear/stream/f0b8970b-cacb-4a9f-83ee-2ef29db47129:CBF2/loc/CBF2/network/51636543/event/sN_IYUG8STe1ZzhIIE_ksA/media/
Události průběhu (Progress) umožňují odlišit přehrávání během reklamní přestávky od přehrávání mimo ni. K žádným jiným účelům při měření reklam neslouží.
Události průběhu můžete identifikovat tak, že v souboru JSON s metadaty vyhledáte identifikátor média a ověříte, zda je pole type nastavené na hodnotu progress. Událost Progress ID3 lze použít například k zablokování ovládacích prvků videa.
Zjištění, kdy reklamní přestávka ve streamu začala nebo skončila pomocí DAI API
Do segmentů reklam vkládá DAI metadata ID3 kvartilových událostí (zahájení, první čtvrtina, středový bod, tři čtvrtiny a dokončení) a do segmentů reklam a prvků slate vkládá události průběhu (po každé sekundě). Při prvním zjištění takové značky ID3 může být vyvolána událost zahájení reklamní přestávky. Pokud určitou dobu (například 2, 5 sekundy) nejsou zaznamenány žádné takové značky ID3, může být vyvolána událost ukončení reklamní přestávky. Značky ID3 vložené pomocí DAI lze identifikovat podle předpony „google_“ a podle přítomnosti v souboru JSON metadat.
Dynamická aktualizace cílení nebo párů klíč–hodnota pro jednotlivé uživatelské streamy
Pomocí parametru session_update_url lze nahradit všechny parametry značky reklamy použité v nadcházejících žádostech o reklamy pro živý přenos (podobně jako pomocí metody replaceAdTagParameters). Hodí se to v případech, kdy je informace o cílení potřeba aktualizovat u jednotlivých programů a uživatelů (např. u živých přenosů sportovních událostí, u kterých nemusí být předem známo cílení).