Inleiding
Adconfig.Ster - https://adconfig.ster.nl/ - is een service die aangeroepen kan worden om de aanroep/url voor een advertentie server te ontvangen. Op basis van informatie als wel of geen consent, wordt bepaald welke advertentie server, met wat voor details moet worden aangeroepen. In de nieuwste NPO Player wordt deze functionaliteit ingebouwd.
Details van het programma kunnen bepalen dat geen advertentie server aanroep wordt teruggegeven, zoals bij gevoelige content die niet van een advertentie mag worden voorzien, ZAPPE, en bij korte content die maar in 20% van de gevallen van een (korte) advertentie hoeft te worden voorzien.
Anders dan met behulp van de oude config, hoeft de videoplayer dus niet meer op basis van JSON een url samen te stellen. Ook is het niet meer nodig om altijd twee advertentie server aanroepen uit te voeren zoals in huidige implementatie met de aanroep van Google DFP het geval is.
Per streamstart dient Adconfig maximaal 1 maal aangeroepen te worden.
Scroll naar het einde van deze pagina voor versiehistorie en wijzigingen.
Werking
Roep voor het verkrijgen van de ad server aanroep, de config aan met https://adconfig.ster.nl/adurl/[identifier], waarbij [identifier] vervangen dient te worden met een voor de app of website unieke identifier, met als formaat [site]-[device].
Voor de NPO zijn de volgende identifiers beschikbaar: npo-app-desktop, npo-app-ios-smartphone, npo-app-ios-tablet, npo-app-android-smartphone, npo-app-android-tablet, npo-app-smarttv, npo-app-tvos (voor AppleTv), npo-app-chromecast.
Voor andere omroepen gelden dezelfde identifiers, waarbij 'npo-app' vervangen dient te worden door de site (lowercase, zonder streepjes). Voorbeeld: pauw-desktop, bnnvara-desktop, bnnvara-ios-smartphone, et cetera.
In de adurl/[identifier] aanroep zijn twee variabelen verplicht:
ncc
cust_params
hierin alle waardes uit onderstaande tabel 'encoded'. Als de waarde van een veld niet beschikbaar is, dient het veld meegenomen te worden met een lege string als waarde. En de 'encoding' betreft standaard encoding zoals in c# gedaan kan worden met HttpUtility.UrlEncode. Hierna zie je ipv;
'=' de waarde '%3D'
'&' de waarde '%26'
',' de waarde '%2C'
_et cetera. Ook kan https://urldecode.org/ handig zijn.
| Veld in cust_params | Omschrijving |
| programma_titel | De naam van het programma. Alleen kleine letters (geen spaties, streepjes, leestekens en speciale karakters). |
| genre | Hier dient het gewenst genre opgegeven te worden, komma-gescheiden. Wanneer het gaat om een jeugd programma, dan moet de waarde jeugd in de lijst opgenomen worden (geen spaties). |
| video_duur | De totale duur van de af te spelen video, in seconden. |
| prid | Het ID van het programma. |
| srid | Het ID van de serie. |
| net | Bij jeugdprogrammering dient hier zapp (of indien van toepassing: zappe) ingevuld te worden, anders npo1, npo2 of npo3. |
| player | Keuze uit web (website players op desktop), smarttv (SMART TV applicaties), mobiel (mobiele website, dus de browsers) en app (voor mobiele apps). |
| devicetype | Device type volgens IAB OpenRTB specs 2.2: 1=Mobile/Tablet, 2=Personal Computer, 3=Connected TV, 4=Phone, 5=Tablet, 6=Connected Device, 7=Set Top Box. Zie paragraaf 5.21 van de IAB's OpenRTB API Specification. |
| os | Deze dient gevuld te worden met een kernmerk van het OS (besturingssysteem): windows, linux, osx, ios, android. Als dit uitgelezen kan worden op de client. Mits dit uitgelezen kan worden vanuit de client. |
| osversion | De versie van het OS (besturingssysteem). Mits dit uitgelezen kan worden vanuit de client. |
| playerversion | De versie van jouw applicatie/player. Mits dit uitgelezen kan worden vanuit de client. |
| omroep | De naam van de omroep in default formaat (kleine letters en geen koppel-streepjes). Bijvoorbeeld: npo, nos, avrotros, ntr, bnnvara, vpro, max, eo, kro, bnn, ncrv, vara, powned, wnl, tros of avro. In het geval van meerdere omroepen komma-gescheiden. |
| afleverings_titel | Titel van de aflevering. Alleen kleine letters (geen spaties, streepjes, leestekens en speciale karakters). |
| subgenre | Subgenre (evt een komma gescheiden lijst, geen spaties). |
| site | Korte naam van de site (bij web meestal: url van de website zonder https://www en .nl) van de website waar de player is geimplementeerd, als nos, npo, dewerelddraaitdoor, wieisdemol, zapp. Bij app's korte naam van de app. |
| ai | Dit dient gevuld te worden met het ID van het betreffende device (IDFA (iOS) of AdID (Android)), bijvoorbeeld het device-id voor een smartphone of tablet. Kenmerk is niet verplicht voor niet-mobiele players. Voor players in een app is het wel verplicht, en als het niet achterhaald kan worden is de volgende waarde valide: 00000000-0000-0000-0000-000000000000. Letop: als consent ontbreekt mag dit veld geen ID bevatten, maar is null gewenst. |
| referrer_url | Url van pagina van stream. Veld is leeg bij apps. Als ingevuld dient op dit veld apart encoding te worden toegepast, zodat het double encoded in cust_params terechtkomt. Om foutgevoeligheid te verminderen aan einde van de cust_params. |
| description_url | Url van beschrijving van stream (meestal hetzelfde als referrer_url, en dient dan leeg te blijven). Veld is leeg bij apps. Als ingevuld dient op dit veld apart encoding te worden toegepast, zodat het double encoded in cust_params terechtkomt. Om foutgevoeligheid te verminderen aan einde van de cust_params. |
De volgende antwoorden zijn mogelijk (response formaat is JSON, met 1 variabele: adUrl die linkt naar);
Zonder consent retourneert de adUrl alleen 'simpel VAST', zoals al ondersteund wordt. Als de response niet leeg is, speelt de videoplayer voor de Omroep stream, de 1 of 2 advertenties.
Ook kan door '&test=true' aan de Adconfig-aanroep toe te voegen, een advertentie testnetwerk gebruikt worden. Voorlopig is dit alleen beschikbaar voor de wel-consent route.
Voorbeelden
De volgende consent en no-consent voorbeeld aanroepen voor desktop, zijn volledig gelijk behalve de ncc waarde.
De volgende aanroep met genre=jeugd en net=zappe geeft een lege response. Er kan dan direct naar de Omroep stream gesprongen worden.
Versiehistorie en wijzigingen
1.1 - huidige versie 7 december 2018. Wijzigingen: 2 kleine updates (referrer_url en description_url encoded naar einde aanroep), verduidelijking identifier [site]-[device], 1 extra veld (device type volgens IAB specs).
1.0 - initiele versie zomer 2018.