De API voor dynamische advertentie-invoeging (DAI) biedt toegang tot streams waarmee inkomsten worden gegenereerd en waarvoor de IMA-SDK niet wordt ondersteund (bijvoorbeeld smart-tv's). De IMA is vereist op platforms waar deze beschikbaar is. De API ondersteunt alle bestaande DAI-functies, maar moet door de uitgever worden geïmplementeerd.
Vereisten voor het gebruik van de API
De volgende functionaliteit moet door uitgevers worden geïmplementeerd als de API wordt gebruikt:
- Toegang krijgen tot de DAI-stream via het HTTP-eindpunt en json-reacties verwerken
- De API-parameters en sleutel/waarden voor targeting samenstellen
- De gebruikerservaringen implementeren (bijvoorbeeld klikbare gebieden en iconen)
- Luisteren naar ID3-gebeurtenissen in de speler om bedieningselementen voor de speler en advertentietracking/-meting te implementeren voor zowel live lineair als VOD
- Functionaliteit voor doorlopen, terugspringen en bookmarks implementeren
- Selectie van streaming-indelingen: HLS of DASH
U kunt de volgende informatie gebruiken voor het aanvragen en verwerken van streams via de API voor video on demand of live lineaire streams.
Video on demand (VOD)
De VOD-API volgt een eenvoudige levenscyclus van het maken van streams tot het verifiëren van de advertentieweergave:
-
Vraag een stream aan met HTTP POST via de contentbron-ID (
cmsid) en video-ID (vid), met API-sleutel of HTML-token en parameters voor advertentietargeting.https://dai.google.com/ondemand/v1/hls/content/<contentId>/vid/<vid>/stream -
Verwerk de reactie voor het manifest voor content afspelen, ondertiteling, advertentie-onderbreking en informatie over de timing van content.
{"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": [...]} -
Voor elke advertentie-onderbreking verwerkt u de afzonderlijke advertentiegegevens voor advertentie-elementen, zoals doorklikken, begeleidende advertenties en de duur van de advertentie-onderbreking voor weergave in de gebruikersinterface.
{"clickthrough_url": "https://dai.google.com/.../videoclick/1835622921898938400","description": "Example pre-roll ad","duration": 10,"seq": 1,"title": "Example pre-roll"} -
Voor elke advertentie activeert u de
media_verification_urlmet de toegevoegde ID3-waarde uit de advertentiemediaweergave.https://dai.google.com/view/p/service/vod/stream/3647080d-c223-442e-a364-c456ee712ece/loc/CBF/network/124319096/content/2474148/vid/bbb-clear/media/
De Progress-gebeurtenissen worden geleverd om onderscheid te maken tussen weergave binnen en buiten een advertentie-onderbreking en hebben geen andere advertentietrackingdoeleinden.
U kunt Progress-gebeurtenissen identificeren door in het json-bestand met metadata te zoeken naar de media-ID en na te gaan of het veld type is ingesteld op progress. De Progress ID3 kan bijvoorbeeld worden gebruikt om de videobedieningselementen te blokkeren.
Live lineaire streams
De lineaire API volgt een eenvoudige levenscyclus van het maken van streams tot het verifiëren van de advertentieweergave:
-
Vraag een stream aan met HTTP POST via de gebeurtenis-ID, met API-sleutel of HTML-token en parameters voor advertentietargeting.
https://dai.google.com/linear/v1/hls/event/<eventid>/stream
https://dai.google.com/linear/v1/dash/event/<eventid>/stream -
Verwerk de reactie voor het manifest voor content afspelen, ondertiteling, advertentie-onderbreking en informatie over de timing van content.
{"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",} -
Vraag de advertentiemetadata aan op de pollingfrequentie of voor elke ID3-advertentiemedia-ID, waarbij u de advertentiemedia-ID toevoegt aan de metadata-URL in een queryparameter.
{"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"}, ...}} -
Voor elke advertentie activeert u de
media_verification_urlmet de toegevoegde ID3-waarde uit de advertentiemediaweergave.https://dai.google.com/view/p/service/linear/stream/f0b8970b-cacb-4a9f-83ee-2ef29db47129:CBF2/loc/CBF2/network/51636543/event/sN_IYUG8STe1ZzhIIE_ksA/media/
De Progress-gebeurtenissen worden geleverd om onderscheid te maken tussen weergave binnen en buiten een advertentie-onderbreking en hebben geen andere advertentietrackingdoeleinden.
U kunt Progress-gebeurtenissen identificeren door in het json-bestand met metadata te zoeken naar de media-ID en na te gaan of het veld type is ingesteld op progress. De Progress ID3 kan bijvoorbeeld worden gebruikt om de videobedieningselementen te blokkeren.
Waarnemen wanneer een advertentie-onderbreking in de stream is gestart/beëindigd met de DAI-API
DAI voegt ID3-metadata voor kwartielgebeurtenissen (zoals Start, Eerste kwartiel, Middelpunt, Derde kwartiel en Volledig) toe aan advertentiesegmenten en voortgangsgebeurtenissen (elke seconde) aan advertentie- en slatesegmenten. Wanneer een dergelijke ID3-tag voor het eerst wordt waargenomen, kan de gebeurtenis 'Advertentiepauze gestart' worden geactiveerd. Daarna kan wanneer deze ID3-tags bijvoorbeeld 2,5 seconden niet worden gevonden, de gebeurtenis 'Advertentie-onderbreking beëindigd' worden aangeroepen. Door DAI ingevoegde ID3-tags zijn te herkennen aan het voorvoegsel google_ en hun aanwezigheid in het json-bestand voor metadata.
Targeting en/of sleutel/waarden dynamisch updaten per gebruikersstream
De session_update_url kan worden gebruikt om alle advertentietagparameters te vervangen die worden gebruikt voor aankomende advertentieverzoeken voor een livestream (vergelijkbaar met replaceAdTagParameters). Dit is handig in gevallen waarin de targetinginformatie per programma en per gebruiker moet worden geüpdatet (bijvoorbeeld voor live sportwedstrijden waarbij de targeting mogelijk niet van tevoren bekend is).