Allgemeiner Überblick

Der Zweck der API besteht darin, Kunden die Möglichkeit zu geben, ihre eigene Einwilligungsschnittstelle zu entwickeln, wenn die von Consentmanager bereitgestellten SDKs nicht ausreichen. Die API ermöglicht es dem Kunden daher, auf der Grundlage der von der API bereitgestellten Informationen eine eigene grafische Benutzeroberfläche zu erstellen. Darüber hinaus ermöglicht die API dem Kunden die Nutzung von Industriestandards wie dem IAB TCF oder IAB GPP, ohne dass eigene Encoder/Decoder implementiert werden müssen.

Umsetzung

Die Umsetzung besteht aus vier Teilen:

1. TV-API
   Sie ermöglicht die Abfrage von Informationen zu Text, Farben, Schaltflächen und Links, die in der Consent-Oberfläche angezeigt werden sollen.
   Die TV-API wird von Consentmanager bereitgestellt.
   
   
2. Einwilligungs-Interface
   Es zeigt die Einwilligungsmeldung an, damit der Endnutzer eine Entscheidung treffen kann.
   Dies ist vom App-Entwickler zu erstellen.
   
   
3. Speicherung
   der Einwilligungen Sobald eine Auswahl getroffen wurde, speichert das Einwilligungsspeicher diese Auswahl, um die Informationen bei Bedarf zu nutzen.
   Dies muss vom App-Entwickler erstellt werden.
   
   
4. QR-Code / Benutzeroberfläche
   für benutzerdefinierte Einstellungen Wenn der Endnutzer neben „Akzeptieren“ oder „Ablehnen“ weitere individuelle Entscheidungen treffen möchte, kann die App einen speziellen QR-Code anzeigen, den der Endnutzer mit seinem Mobiltelefon scannen kann. Der Endnutzer wird auf eine Website weitergeleitet, auf der er seine Auswahl treffen kann. Sobald dies geschehen ist, werden die Einstellungen über die TV-API an das TV-Gerät zurückgesendet und der Endnutzer kann die App weiter nutzen.
   Dies wird von consentmanager bereitgestellt.

Einschränkungen

Da der Kunde seine eigene Benutzeroberfläche implementieren wird, bietet die API im Vergleich zu einer normalen Web- oder App-Integration nicht den vollen Funktionsumfang. Unter anderem sind die folgenden Funktionen nicht Teil der API (unter anderem):

CMP-Einstellungen · Integrationen (z. B. Adobe, Awin, etracker usw.) · Datenschutz-APIs (DNT, GPC, ADPC, …) · Automatische Blockierung · Altersüberprüfung · Eingeschränkte Berichtsfunktionen

Design-Einstellungen · Feldgröße und -position · Schriftgröße und -art · Umschaltflächen / Kontrollkästchen auf der ersten Ebene · Symbole für Funktionen, Schaltflächen und Links · Unterstützung für WCAG · Verhaltenslogik und Effekte

Keine Einschränkungen bei den Einstellungen

Abgesehen von den oben genannten Einschränkungen gibt es noch viele Funktionen, die Teil der API sind (sobald sie vollständig in Ihre App integriert ist) und wie gewohnt genutzt werden können. Dazu gehören unter anderem:

• Automatische Anpassung der Texte an die Sprache des Nutzers
• Darstellung der Einwilligungsschicht in den über CMP / Design festgelegten Farben
• Unterstützung für IAB TCF, IAB GPP, Google Consent Mode
• A/B-Tests & maschinelles Lernen verschiedener Designs
• Ausrichtung der Designs auf Endnutzer basierend auf Sprache, Land oder anderen Merkmalen
• (begrenzte) Berichterstattung über Nutzer, angezeigte Einwilligungsbildschirme und Auswahlmöglichkeiten

Einrichtung

Voraussetzungen

Um die API nutzen zu können, benötigen Sie ein Consentmanager-Konto, bei dem die Funktion „TV SDK“ aktiviert ist (in der Regel in den höheren Paketen enthalten). Sie können überprüfen, ob die Funktion enthalten ist, indem Sie sich in Ihr Konto einloggen und zu Menü > CMPs > TV navigieren. Wenn Sie den Menüpunkt „TV“ nicht sehen, wenden Sie sich bitte an Ihren Kundenbetreuer, um Ihr Konto zu aktualisieren.

TV-API aktivieren

Um die API nutzen zu können, müssen Sie in Ihrem ConsentManager-Konto ein CMP erstellen und die TV-API aktivieren. Die CMP sollte denselben Einstellungen folgen, die du normalerweise für eine Webumgebung vornehmen würdest, d. h. du musst die allgemeinen Einstellungen der CMP vornehmen und Zwecke sowie Anbieter hinzufügen. Sobald dies erledigt ist, navigiere zu Menü > CMPs > TV und aktiviere den Schalter bei „TV-API aktivieren“.

Sobald die API aktiviert ist, sehen Sie den API-Endpunkt unterhalb des Schalters. Kopieren Sie die Endpunkt-URL für die weitere Verwendung in Ihrer Implementierung.

API-Flow

Um die Einwilligungsschnittstelle in eine App zu implementieren, ruft der App-Entwickler die TV-API auf, um Informationen darüber zu erhalten, ob der Einwilligungsbildschirm diesem bestimmten Nutzer angezeigt werden soll oder nicht. Die API enthält auch Informationen zu Farben und Texten, die dem Endnutzer präsentiert werden sollen, sowie dazu, welche Schaltflächen und Links angezeigt werden sollen. Sobald der Endnutzer eine Auswahl getroffen hat, informiert die App das ConsentManager-System über die TV-API über diese Auswahl und erhält im Gegenzug die Einwilligungsdaten (z. B. IAB-TCF-Einwilligungsstring, IAB-GPP-String, Liste der aktivierten Anbieter, Liste der Zwecke usw.). Die App kann diese Einwilligungsdaten dann nutzen, um Datenverarbeitungsaktivitäten festzulegen oder sie an Dritte weiterzugeben (z. B. den IAB-TCF-Einwilligungsstring).

Detailliertes Flussdiagramm

Nachstehend finden Sie das detaillierte Flussdiagramm für die Implementierung der TV-API. Die Schritte lauten wie folgt:

1. App starten
2. Die App ruft Daten aus dem Consent Store ab (falls vorhanden)
3. Die App ruft den TV-API-Endpunkt „AppStart“ auf und übergibt die vorhandene Einwilligungszeichenfolge
4. Die TV-API antwortet mit „displayLayer“ auf „true“ oder „false“, um anzugeben, ob die Einwilligungsschnittstelle angezeigt werden soll
5. (Wenn displayLayer = true) Die App zeigt die Einwilligungsoberfläche unter Verwendung der Informationen aus der TV-API an
6. Der Nutzer klickt auf „Akzeptieren“: Die App ruft den TV-API-Endpunkt „Feedback“ für die
   Zustimmung auf –> Die App speichert die Einwilligungsdaten und fährt wie gewohnt fort
7. Der Nutzer klickt auf „Ablehnen“: Die App ruft den TV-API-Endpunkt „Feedback“ für
   „Ablehnen“ auf –> Die App speichert die Einwilligungsdaten und fährt wie gewohnt fort
8. Der Nutzer klickt auf „Einstellungen“: Die App zeigt einen QR-Code an
9. Die App ruft alle 3 Sekunden den TV-API-Endpunkt „QR-Status“ auf, um den Status abzufragen.
10. Sobald der QR-Status „fertig“ ist (oder der Nutzer auf die Schaltfläche „Zurück“ klickt), speichert die App die Einwilligungsdaten und fährt wie gewohnt fort

AppStart Endpunkt

Die URL des AppStart-Endpunkts finden Sie in Ihrem Consentmanager-Login-Bereich (siehe Abschnitt „Einrichtung“ oben). Der Endpunkt gibt ein JSON-Objekt zurück und liefert Ihnen zwei Informationen:

1. Ob die Einwilligungsschnittstelle angezeigt
   werden soll oder nicht Dies wird durch die Eigenschaft „displayLayer“ mit dem Wert „true“ (Einwilligungsschnittstelle anzeigen) oder „false“ (Einwilligungsschnittstelle muss nicht angezeigt werden) signalisiert.
   
   
2. Welches Styling sollte verwendet werden, falls du die Einwilligungsschnittstelle
   anzeigen musst/möchtest? Dies wird durch die Eigenschaft „display“ signalisiert.

Aufruf des AppStart-Endpunkts

Wenn du den AppStart-Endpunkt aufrufst, solltest du die URL verwenden, die dir in deinem Consentmanager-Login-Bereich zur Verfügung gestellt wurde. Zusätzlich solltest du die URL um die folgenden Parameter erweitern:

Parameter	Beschreibung
&l=…	(optional, empfohlen) Gewünschte Sprache für die Anzeige. Z. B. &l=DE oder &l=EN-US. Die API gibt die Texte in dieser Sprache zurück.
&appid=…	(optional, empfohlen) Kennung der App. Z. B. &appid=123456 oder &appid=my-app-name
&cs=…	(optional, erforderlich, falls vorhanden) Der gespeicherte Consent-String der letzten Auswahl des Nutzers. Der Consent-String wird an die App übergeben über: a) den Feedback-Endpunkt unter der Eigenschaft „consentstring“ oder b) den QR-Status-Endpunkt unter der Eigenschaft „feedbackobject.consentstring“
&ip=…	(optional) IP-Adresse des Nutzers, die für Geolokalisierungszwecke verwendet werden soll. Wenn keine IP übergeben wird, wird die IP der Anforderungsquelle verwendet. Z. B. &ip=123.123.123.123

AppStart-Endpunktantwort

Die API-Antwort ist ein JSON-kodiertes Objekt im folgenden Format:

{
 "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
 }
}

Gestaltung der Einwilligungsschnittstelle

Insbesondere bei der Verwendung von Branchenstandards wie dem IAB TCF oder IAB GPP ist consentmanager grundsätzlich verpflichtet, sicherzustellen, dass bestimmte Standards von seinen Kunden eingehalten werden. Wir müssen daher von allen Kunden verlangen, dass sie die über den AppStart-Endpunkt bereitgestellten Informationen zur Gestaltung der Einwilligungsschnittstelle verwenden.

IAB TCF & GPP-Konformität

Um die Einhaltung der IAB TCF- und GPP-Richtlinien sicherzustellen, müssen wir von allen Kunden verlangen, dass sie die über den AppStart-Endpunkt bereitgestellten Elemente verwenden, insbesondere:

1. Die Einwilligungsschnittstelle muss auf dem ersten Bildschirm eine Überschrift und einen Text anzeigen. Überschrift und Text müssen aus der API übernommen und vollständig angezeigt werden. Sie dürfen nicht verdeckt, gekürzt oder auf andere Weise unsichtbar gemacht werden.
2. Die Einwilligungsschnittstelle muss die von der API angegebenen Schaltflächen mit dem von der API vorgegebenen Beschriftungstext anzeigen. Die Schaltflächen müssen sofort sichtbar sein und dürfen nicht verdeckt werden.
3. Die Einwilligungsschnittstelle muss die von der API angegebenen Links anzeigen. Die Links müssen für den Kunden zugänglich sein, müssen aber nicht sofort sichtbar sein. Wir empfehlen jedoch, alle Links immer sichtbar zu machen.
4. Die Einwilligungsschnittstelle muss die von der API vorgegebenen Farben verwenden. Ist dies aufgrund von Gerätebeschränkungen nicht möglich, muss die Einwilligungsschnittstelle so gestaltet sein, dass alle Schaltflächen die gleiche Bedeutung haben.

Feedback-Endpunkt

Die Antwort des AppStart-Endpunkts enthält zwei URLs über „feedback.accept“ und „feedback.reject“. Diese URLs müssen von der App aufgerufen werden, sobald der Nutzer sich entscheidet, die Datenschutzeinstellungen zu akzeptieren oder abzulehnen.

Aufruf des Feedback-Endpunkts

Die URLs der Feedback-Endpunkte werden bereits durch den AppStart-Endpunkt-API-Aufruf vorgefertigt und müssen nicht geändert oder ergänzt werden. Bitte rufen Sie die richtige URL auf, die der Auswahl des Benutzers entspricht.

Feedback-Endpunkt-Antwort

Die API-Antwort ist ein JSON-kodiertes Objekt im folgenden Format:

{
 "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 Endpoint

Falls der Nutzer auf „Einstellungen“ klickt, soll die App einen zweiten Einwilligungsbildschirm mit einem QR-Code (und optional einer URL) anzeigen. Der Nutzer scannt dann den QR-Code und trifft seine Datenschutzentscheidungen auf seinem Mobiltelefon. Während der Nutzer dies tut, soll die App den aktuellen Status des Vorgangs überprüfen.

Zu diesem Zweck enthält die Antwort des AppStart-Endpunkts eine URL über „customsettings.statusurl“. Diese URL muss von der App aufgerufen werden, sobald der QR-Code dem Nutzer angezeigt wird. Wir empfehlen, die URL alle 3 Sekunden aufzurufen, um nach Updates zu suchen.

Aufruf des Feedback-Endpunkts

Die Endpunkt-URL des QR-Codes wird bereits durch den AppStart-Endpunkt-API-Aufruf vorgefertigt und muss nicht geändert oder ergänzt werden. Bitte rufen Sie den Aufruf alle 3 Sekunden auf, während der Nutzer seine Auswahl trifft.

QR-Code-Endpunktantwort

Die API-Antwort ist ein JSON-kodiertes Objekt im folgenden Format:

{
 "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
 {
  ...
 }
}

Weitere Informationen zur Umsetzung

Einwilligungsspeicherung

Sobald der Nutzer eine Auswahl getroffen hat oder der QR-Code-Vorgang abgeschlossen ist, gibt die API das Feedback-Objekt mit allen Details zurück. Wir empfehlen App-Entwicklern, das vollständige Objekt zu speichern.

Fehlerbehandlung

Da die App auf einen Aufruf einer externen API angewiesen ist, empfehlen wir verschiedene Strategien zur Fehlerbehandlung, um Probleme und eine schlechte Benutzererfahrung zu vermeiden:

• API-Fehler
  Falls eine API einen unerwarteten HTTP-Statuscode zurückgibt (z. B. 4xx, 5xx oder 6xx), muss die App dies als Fehler behandeln. Die App sollte auf einen Standardzustand oder eine Standardlogik zurückgreifen und die nächsten Schritte im Prozess überspringen. In Fällen, in denen ein HTTP-Statuscode 3xx gesendet oder anderweitig eine Standortänderung signalisiert wird, muss die App der signalisierten URL folgen (Hinweis: Wende eine Regel für die maximale Anzahl von Weiterleitungen an, um Endlosschleifen zu vermeiden).
  
  
• Timeouts
  Alle API-Aufrufe müssen ein maximales Timeout haben, z. B. 15 Sekunden. Wenn die API innerhalb dieses Zeitraums nicht antwortet, sollte sie als offline betrachtet werden. Die App sollte auf einen Standardzustand oder eine Standardlogik zurückgreifen und die nächsten Schritte im Prozess überspringen.
  
  
• SSL-Validierung
  Insbesondere bei älteren Geräten kann die SSL-Validierung zu Problemen führen, wenn Zertifikatsversionen oder Verschlüsselungsmethoden nicht mehr unterstützt werden. In diesem Fall können App-Entwickler die API-Endpunkte über HTTP statt über HTTPS aufrufen.
  
  
• Parsing-Fehler
  Alle API-Endpunkte geben JSON-Objekte als UTF-8-kodierte Zeichenfolgen zurück. Beim Parsen der Zeichenfolge sollte die App überprüfen, ob das Parsing wie erwartet funktioniert hat. Darüber hinaus muss die App:
  • Behandeln Sie alle Eigenschaften aller Objekte als optional und prüfen Sie immer, ob eine Eigenschaft vorhanden ist, bevor Sie darauf zugreifen.
  • Prüfe, ob der Rückgabewert einer Eigenschaft vom erwarteten Datentyp ist (z. B. String, Bool oder Integer).
  • Sei flexibel bei der Objektstruktur. Einige Objekte haben eine dynamische Struktur und können mit mehr oder weniger Eigenschaften auftreten. Wenn eine App eine Eigenschaft nicht kennt, soll sie diese ignorieren.
    
    
• QR-Code-Statusfehler
  In Fällen, in denen der QR-Code-Status-Endpunkt status=error zurückgibt, sollte die App die Einholung der Einwilligung abbrechen und wie gewohnt fortfahren.
  
  
• QR-Code entfernt

In Fällen, in denen der QR-Code angezeigt wird, aber über einen längeren Zeitraum keine Statusänderung zu beobachten ist, soll die App zur ursprünglichen Einwilligungsseite (erster Bildschirm) zurückkehren und dem Nutzer eine erneute Auswahl ermöglichen. Wir empfehlen eine maximale Wartezeit von 5 Minuten, bevor zur ersten Seite zurückgekehrt wird.

Versionsverwaltung

Die API-Versionen werden über die AppStart-Endpunkt-URL verwaltet. Im Falle einer API-Änderung werden wir die AppStart-Endpunkt-URL auf eine neue Version aktualisieren, um zu ermöglichen, dass mehrere Versionen gleichzeitig aktiv sind.