[CTV-API] Integratie

Algemeen overzicht

Het doel van de API is om klanten in staat te stellen hun eigen toestemmingsinterface te ontwikkelen voor gevallen waarin de SDK's die door consentmanager zijn niet voldoende. De API stelt de klant daarom in staat om zijn eigen grafische interface te bouwen op basis van de informatie die de API verstrekt. Bovendien stelt de API de klant in staat om industriestandaarden zoals de IAB TCF of IAB GPP te gebruiken zonder dat hij zijn eigen encoders/decoders hoeft te implementeren.

Implementatie

De implementatie bestaat uit vier onderdelen:

1. TV-API
   Hiermee kunt u informatie opvragen over de tekst, kleuren, knoppen en links die in de toestemmingsinterface moeten worden weergegeven.
   De TV API wordt geleverd door consentmanager.
   
   
2. Toestemmingsinterface
   Hier wordt het toestemmingsbericht weergegeven, zodat de eindgebruiker een keuze kan maken.
   Deze moet door de app-ontwikkelaar worden gemaakt.
   
   
3. Toestemmingsopslag
   Zodra er een keuze is gemaakt, worden deze keuzes opgeslagen in de toestemmingsopslag, zodat de informatie kan worden gebruikt wanneer dat nodig is.
   Deze moet door de app-ontwikkelaar worden gemaakt.
   
   
4. QR-code / interface voor aangepaste instellingen
   Als de eindgebruiker naast accepteren of afwijzen ook andere keuzes wil maken, kan de app een specifieke QR-code tonen die de eindgebruiker met zijn of haar mobiele telefoon kan scannen. De eindgebruiker wordt dan doorgestuurd naar een website waar hij of zij zijn of haar keuzes kan maken. Vervolgens worden de keuzes via de TV API teruggestuurd naar het tv-toestel en kan de eindgebruiker de app blijven gebruiken.
   Dit wordt verzorgd door consentmanager.

Beperkingen

Omdat de klant zijn eigen interface implementeert, biedt de API niet de volledige functionaliteit in vergelijking met een normale web- of app-integratie. Onder andere de volgende functies maken geen deel uit van de API:

Let op: de hierboven genoemde instellingen worden niet via de API verzonden, maar kunnen handmatig door de app-ontwikkelaar worden geïmplementeerd.

Geen beperkingen op instellingen

Naast de bovengenoemde beperkingen zijn er nog steeds veel functies die deel uitmaken van de API (wanneer ze volledig in uw app zijn geïmplementeerd) en die u gewoon kunt gebruiken. Dit zijn onder andere:

• Automatische aanpassing van teksten aan de taal van de gebruiker
• Weergave van de toestemmingslaag in de via CMP/Design ingestelde kleuren
• Ondersteuning voor IAB TCF, IAB GPP, Google Consent Mode
• A/B-testen en machine learning van verschillende ontwerpen
• Targeting van ontwerpen op eindgebruikers op basis van taal, land of andere kenmerken
• (beperkt) Rapportage van gebruikers, getoonde toestemmingschermen en keuzes

Setup

Voorwaarden

Om de API te kunnen gebruiken, moet u een consentmanager Account met de functie "TV SDK" ingeschakeld (meestal inbegrepen in de duurdere pakketten). U kunt zien of de functie is inbegrepen door in te loggen op uw account en naar Menu > CMP's > TVAls u het menu-item 'TV' niet ziet, neem dan contact op met uw accountmanager om uw account te upgraden.

TV API inschakelen

Om de API te kunnen gebruiken, moet u een CMP in uw consentmanager account en schakel de TV API in. De CMP volgt dezelfde instellingen als u normaal gesproken voor een webomgeving zou gebruiken. Dit betekent dat u de algemene instellingen van de CMP moet instellen en doelen en leveranciers moet toevoegen. Navigeer vervolgens naar Menu > CMP's > TV en activeer de schakelaar op TV API inschakelen.

Zodra de API is ingeschakeld, ziet u het API-eindpunt onder de schakelaar. Kopieer de eindpunt-URL voor verder gebruik in uw implementatie.

Opmerking: Zodra de API is ingeschakeld, duurt maximaal 1 uur voordat het API-eindpunt bruikbaar wordt. Houd er ook rekening mee dat wijzigingen in de CMP- of ontwerpinstellingen van invloed zijn op de functionaliteit. alleen dagelijks binnen de TV API.

API-stroom

Om de toestemmingsinterface in een app te implementeren, zal de app-ontwikkelaar de TV API aanroepen om informatie te ontvangen over het al dan niet tonen van het toestemmingsscherm aan deze specifieke gebruiker. De API zal ook informatie bevatten over kleuren en teksten die aan de eindgebruiker worden gepresenteerd, evenals welke knoppen en links worden weergegeven. Zodra de eindgebruiker een keuze heeft gemaakt, zal de app de consentmanager systeem via de TV API over deze keuze en ontvangt in ruil daarvoor de toestemmingsgegevens (bijv. IAB TCF-toestemmingsreeks, IAB GPP-reeks, lijst met geactiveerde leveranciers, lijst met doeleinden, enz.). De app kan deze toestemmingsgegevens vervolgens gebruiken om gegevensverwerkingsactiviteiten te bepalen of deze aan derden te verstrekken (bijv. de IAB TCF-toestemmingsreeks).

Gedetailleerd stroomschema

Hieronder vindt u het gedetailleerde stroomschema voor de implementatie van de TV API. De stappen zijn als volgt:

1. App-start
2. App haalt gegevens op uit toestemmingsopslag (indien aanwezig)
3. App roept TV API-eindpunt "AppStart" aan en geeft bestaande toestemmingsreeks door
4. De TV API reageert met “displayLayer” ingesteld op “true” of “false” om aan te geven dat de toestemmingsinterface moet worden weergegeven
5. (Als displayLayer = true) De app geeft de toestemmingsinterface weer met behulp van de informatie van de TV API
6. Gebruiker klikt op Accepteren: App roept TV API-eindpunt 'Feedback' aan voor acceptatie
   -> App slaat toestemmingsgegevens op en gaat gewoon door
7. Gebruiker klikt op Afwijzen: App roept TV API-eindpunt 'Feedback' aan voor afwijzen
   --> App slaat toestemmingsgegevens op en gaat gewoon door
8. Gebruiker klikt op Instellingen: App toont QR-code
9. App roept TV API-eindpunt "QR-Status" elke 3 seconden aan voor statusupdate
10. Zodra de QR-status is “voltooid” (of de gebruiker klikt op de “terug”-knop), slaat de app de toestemmingsgegevens op en gaat verder zoals normaal

AppStart-eindpunt

De URL van het AppStart-eindpunt vindt u in uw consentmanager Inloggebied (zie het gedeelte over instellingen hierboven). Het eindpunt retourneert een JSON-object en geeft u twee stukjes informatie:

1. Of de toestemmingsinterface moet worden weergegeven
   Dit wordt aangegeven door de eigenschap “displayLayer” met de waarde “true” (de toestemmingsinterface weergeven) of “false” (de toestemmingsinterface hoeft niet te worden weergegeven).
   
   
2. Welke styling moet worden gebruikt als u de toestemmingsinterface moet/wilt weergeven?
   Dit wordt aangegeven door de eigenschappen “display”

Het AppStart-eindpunt aanroepen

Wanneer u het AppStart-eindpunt aanroept, moet u de URL gebruiken die u in uw consentmanager Inloggebied. Daarnaast moet u de URL uitbreiden door de volgende parameters toe te voegen:

AppStart-eindpuntrespons

Het API-antwoord is een JSON-gecodeerd object in de volgende indeling:

{
 "displayLayer": true | false, //Whether to display the consent interface or not
 "display":
 {
  "colors":
  {
   "background":        "#...", //Color for the background of the consent interface
   "headline":          "#...", //Color for the headline text
   "text":              "#...", //Color for the normal text
   "comment":           "#...", //Color for less important texts
   "buttonbackground":  "#...", //Color for the background of buttons
   "buttontext":        "#...", //Color for the text in buttons
   "accept":
   {
    "buttonbackground": "#...", //Color for the background of the accept button
    "buttontext":       "#..."  //Color for the text of the accept button
   },
   "reject":
   {
    "buttonbackground": "#...", //Color for the background of the reject button
    "buttontext":       "#..."  //Color for the text of the reject button
   },
   "settings":
   {
    "buttonbackground": "#...", //Color for the background of the settings button
    "buttontext":       "#..."  //Color for the text of the settings button
   },
   "save":
   {
    "buttonbackground": "#...", //Color for the background of the save button
    "buttontext":       "#..."  //Color for the text of the save button
   },
   "highlight":         "#...", //Color for highlighted elements
   "link":              "#..."  //Color for link texts
  },
  "texts":
  {
   "headline":          "...",  //Text for the headline
   "text":              "...",  //Text for the main text
   "accept":            "...",  //Text for the accept button
   "reject":            "...",  //Text for the reject button
   "settings":          "...",  //Text for the settings button
   "save":              "...",  //Text for the save button
   "settingsheadline":  "...",  //Text for the headline in the settings page
   "settingstext":      "...",  //Text for the text in the settings page
   "backlink":          "..."   //Text for the back link in the settings page
  },
  "layout":
  {
   "buttons":           [...],  //Set of strings representing the buttons to be displayed.
                                //Options: "accept", "reject", "settings", "save" (min. 1, max. 3)
   "links":             [...]   //Set of strings representing the links to be displayed
                                //Options: "settings", "privacy", "tac", "imprint" (min. 0, max. 4)

  }
 },
 "links":
 {
  "privacyurl":    "https://...", //Link to privacy policy
  "tacurl":        "https://...", //Link to terms and conditions
  "imprinturl":    "https://..."  //Link to imprint / legal notes
 },
 "customsettings":
 {
  "link":          "https://...", //Link to a webpage where the end-user can customize their settings
  "qrcodeimage":   "https://...", //URL of an image (PNG, 196x196 px) of a QR Code 
                                  //The QR-Code should be displayed to the end-user to allow customization
  "statusurl":     "https://..."  //QR-Status Endpoint URL to be queried for status updates on the end-user
 },
 "feedback":
 {
  "accept":        "https://...", //Feedback Endpoint URL for signaling that the user clicked on accept
  "reject":        "https://..."  //Feedback Endpoint URL for signaling that the user clicked on reject
 }
}

Styling van de toestemmingsinterface

Vooral bij gebruik van industriestandaarden zoals de IAB TCF of IAB GPP, consentmanager is volgens het beleid verplicht ervoor te zorgen dat bepaalde normen door haar cliënten worden nageleefd. Wij Dan moet je vereisen daarom dat alle cliënten de informatie die via het AppStart-eindpunt wordt verstrekt, gebruiken om het ontwerp van de toestemmingsinterface samen te stellen.

Belangrijk: Om ervoor te zorgen dat alle regels worden nageleefd, vereisen alle klanten om een ​​screenshot van de toestemmingsinterface die ze hebben gemaakt, ter goedkeuring in te dienen.

IAB TCF & GPP-naleving

Om te voldoen aan de IAB TCF- en GPP-vereisten, moeten we van alle klanten eisen dat ze de elementen gebruiken die via het AppStart-eindpunt worden geleverd, met name:

1. De toestemmingsinterface moet een kop en tekst op het eerste scherm weergeven. De kop en tekst moeten uit de API komen en volledig worden weergegeven. Ze mogen niet worden verduisterd, ingekort of anderszins onzichtbaar zijn.
2. De toestemmingsinterface moet de door de API aangegeven knoppen weergeven, inclusief de door de API verstrekte labeltekst. De knoppen moeten direct zichtbaar zijn en mogen niet worden afgedekt.
3. De toestemmingsinterface moet de door de API aangegeven links weergeven. Links moeten toegankelijk zijn voor de klant, maar hoeven niet direct zichtbaar te zijn. We raden in ieder geval aan om alle links altijd zichtbaar te maken.
4. De toestemmingsinterface moet de door de API aangegeven kleuren gebruiken. Indien dit vanwege beperkingen van het apparaat niet mogelijk is, moet de toestemmingsinterface zo worden ontworpen dat alle knoppen dezelfde waarde hebben.

Feedback-eindpunt

De respons van het AppStart-eindpunt bevat twee URL's: "feedback.accept" en "feedback.reject". Deze URL's worden door de app aangeroepen zodra de gebruiker de privacyinstellingen accepteert of afwijst.

Het feedback-eindpunt aanroepen

De Feedback Endpoint URL's zijn al vooraf geconstrueerd door de AppStart Endpoint API-aanroep en hoeven niet te worden gewijzigd of toegevoegd. Roep de juiste URL aan die overeenkomt met de keuze van de gebruiker.

Feedback-eindpuntrespons

Het API-antwoord is een JSON-gecodeerd object in de volgende indeling:

{
 "feedback":        "...", //Consent status for the user, one of "accept", "reject", "custom" or "error" 
 "consentstring":   "...", //consentmanager specific consent information to be stored on the device.
                           //This string needs to be passed back with the next request to the AppStart
 
                           //Endpoint as parameter &cs=...
 "vendorConsents":  {...}, //Object of vendors that have consent. Format is "vendorID":true|false
                           //For example: {"s26": true, "c172": false}
                           //Note: If a vendor ID is not present, you MUST assume no consent for this ID
 "vendorLI":        {...}, //Object of vendors that have legitimate interests. Format as above.
 "purposeConsents": {...}, //Object of purposes that have consent. Format as above.
 "purposeLI":       {...}, //Object of purposes that have legitimate interests. Format as above.
 "iabtcf":          "...", //IAB TCF Consent String 
 "iabgpp":          "...", //IAB GPP String
 "addtlConsent":    "...", //Google Additional Consent String
 "metadata":               //List of objects to be stored in device shared storage 
                           //(e.g. NSUserDefaults, SharedPreferences or similar) 
 [
  {                        //Each object in the list contains 3 properties:
   "name":          "...", //Name (or key) of the data to be stored (e.g. keyname for SharedPreferences)
   "value":         "...", //Value to be stored
   "type":          "..."  //Type of the value to be stored, can be “string” or “int”
  },
  ...
 ]
}

QR-code eindpunt

Als de gebruiker op 'Instellingen' klikt, toont de app een tweede toestemmingsscherm met een QR-code (en een optionele URL). De gebruiker scant vervolgens de QR-code en gaat verder met het maken van zijn/haar privacykeuzes op zijn/haar mobiele telefoon. Terwijl de gebruiker dit doet, controleert de app de huidige status van de procedure.

Hiervoor bevat de respons van het AppStart Endpoint een URL via "customsettings.statusurl". Deze URL wordt door de app aangeroepen zodra de QR-code aan de gebruiker wordt getoond. We raden aan de URL elke 3 seconden aan te roepen om te controleren op updates.

Het feedback-eindpunt aanroepen

De QR-code-eindpunt-URL is al vooraf samengesteld door de AppStart Endpoint API-aanroep en hoeft niet te worden gewijzigd of toegevoegd. Roep de URL elke 3 seconden aan terwijl de gebruiker zijn keuzes maakt.

QR-code eindpuntrespons

Het API-antwoord is een JSON-gecodeerd object in de volgende indeling:

{
 "status":         "...", //Status of the process, one of: 
                          //„initialized“ – User did not open the custom settings page yet
                          //„pending“     – User opened the custom settings page 
                          //„finished“    – User finished their choices
                          //„error“       – An error occured

 "feedbackobject":        //In case of status=finished, the object will contain all consent data similar
                          //to the Feedback Endpoint API
 {
  ...
 }
}

Overige implementatie-informatie

Toestemmingsopslag

Zodra de gebruiker een keuze heeft gemaakt of het QR-codeproces is voltooid, retourneert de API het feedbackobject met alle details. We raden app-ontwikkelaars aan het volledige object op te slaan.

Foutafhandeling

Omdat de app afhankelijk is van een aanroep van een externe API, raden we verschillende strategieën voor foutbehandeling aan om problemen en een slechte gebruikerservaring te voorkomen:

• API-fouten
  Als een API een onverwachte HTTP-statuscode retourneert (bijv. 4xx, 5xx of 6xx), behandelt de app dit als een fout. De app moet terugvallen op een standaardstatus of -logica en de volgende stappen in het proces overslaan. In gevallen waarin HTTP-statuscode 3xx wordt verzonden of anderszins een locatiewijziging wordt gesignaleerd, moet de app de gesignaleerde URL volgen (Opmerking: pas een regel voor maximale follow-up toe om oneindige lussen te voorkomen).
  
  
• Time-outs
  Alle API-aanroepen hebben een maximale time-out, bijvoorbeeld 15 seconden. Als de API niet binnen deze tijd reageert, moet deze als offline worden beschouwd. De app moet terugvallen op een standaardstatus of -logica en de volgende stappen in het proces overslaan.
  
  
• SSL-validatie
  Vooral bij oudere apparaten kan SSL-validatie problemen veroorzaken wanneer certificaatversies of encryptiemethoden niet meer worden ondersteund. In dat geval kunnen app-ontwikkelaars de API-eindpunten via http in plaats van https aanroepen.
  
  
• Parseerfouten
  Alle API-eindpunten retourneren JSON-objecten als UTF-8-gecodeerde strings. Bij het parseren van de string moet de app controleren of het parseren naar behoren werkt. Verder moet de app:
  • Behandel alle eigenschappen van alle objecten als optioneel en controleer altijd of een eigenschap bestaat voordat u deze benadert.
  • Controleren of de geretourneerde waarde van een eigenschap van het verwachte gegevenstype is (bijvoorbeeld een tekenreeks, bool of geheel getal).
  • Wees flexibel met de objectstructuur. Sommige objecten hebben een dynamische structuur en kunnen meer of minder eigenschappen hebben. Als een app een eigenschap niet kent, moet deze worden genegeerd.
    
    
• QR-codestatusfout
  In gevallen waarin het QR-Code Status Endpoint status=error retourneert, moet de app het verzamelen van toestemming afbreken en normaal doorgaan.
  
  
• QR-code verlaten

Wanneer de QR-code wordt weergegeven, maar er gedurende langere tijd geen statuswijziging optreedt, keert de app terug naar de interface voor initiële toestemming (eerste scherm) en kan de gebruiker opnieuw een keuze maken. We adviseren een maximale wachttijd van 5 minuten voordat de app terugkeert naar het eerste scherm.

Versiemanagement

De API-versies worden beheerd via de AppStart Endpoint URL. Bij een API-wijziging werken we de AppStart Endpoint URL bij naar een nieuwe versie, zodat meerdere versies tegelijk actief kunnen zijn.