[CTV-API] Integration

Gesamtübersicht

Der Zweck der API besteht darin, Kunden die Entwicklung einer eigenen Zustimmungsschnittstelle für Fälle zu ermöglichen, in denen die von consentmanager reichen nicht aus. Die API ermöglicht es dem Kunden daher, eine eigene grafische Benutzeroberfläche basierend auf den von der API bereitgestellten Informationen zu erstellen. Darüber hinaus ermöglicht die API dem Kunden die Nutzung von Industriestandards wie dem IAB TCF oder IAB GPP, ohne dass er eigene Encoder/Decoder implementieren muss.

Umsetzung

Die Implementierung besteht aus vier Teilen:

1. TV-API
   Es ermöglicht die Abfrage von Informationen zu Text, Farben, Schaltflächen und Links, die in der Zustimmungsoberfläche angezeigt werden sollen.
   Die TV-API wird bereitgestellt von consentmanager.
   
   
2. Zustimmungsschnittstelle
   Es zeigt die Zustimmungsmeldung an, damit der Endbenutzer eine Auswahl treffen kann.
   Diese ist vom App-Entwickler zu erstellen.
   
   
3. Einwilligungsspeicherung
   Sobald eine Auswahl getroffen wurde, speichert der Zustimmungsspeicher diese Auswahl, um die Informationen bei Bedarf zu verwenden.
   Diese ist vom App-Entwickler zu erstellen.
   
   
4. QR-Code / Benutzeroberfläche für benutzerdefinierte Einstellungen
   Möchte der Endnutzer neben „Akzeptieren“ und „Ablehnen“ auch individuelle Auswahlmöglichkeiten treffen, kann die App einen speziellen QR-Code anzeigen, den er mit seinem Mobiltelefon scannen kann. Der Endnutzer wird auf eine Website weitergeleitet, auf der er seine Auswahl treffen kann. Anschließend werden die Auswahlen über die TV-API an das TV-Gerät zurückgesendet, und der Endnutzer kann die App weiter nutzen.
   Dies wird bereitgestellt durch consentmanager.

Einschränkungen

Da der Kunde seine eigene Schnittstelle implementiert, bietet die API im Vergleich zu einer normalen Web- oder App-Integration nicht die volle Funktionalität. Unter anderem sind folgende Funktionen nicht Teil der API:

Hinweis: Die oben genannten Einstellungen werden nicht über die API gesendet, sondern können vom App-Entwickler manuell implementiert werden.

Keine Einschränkungen bei den Einstellungen

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

• Automatische Anpassung der Texte an die Sprache des Benutzers
• Anzeige des Consent Layers in den über CMP / Design eingestellten Farben
• Unterstützung für IAB TCF, IAB GPP, Google Consent Mode
• A/B-Testing und maschinelles Lernen verschiedener Designs
• Ausrichtung der Designs auf Endbenutzer basierend auf Sprache, Land oder anderen Attributen
• (eingeschränkt) Berichterstattung über Benutzer, angezeigte Zustimmungsbildschirme und Auswahlmöglichkeiten

Einrichtung

Voraussetzungen:

Um die API nutzen zu können, benötigen Sie eine consentmanager Konto mit aktivierter Funktion „TV SDK“ (normalerweise in den höheren Paketen enthalten). Sie können sehen, ob die Funktion enthalten ist, indem Sie sich in Ihr Konto einloggen und zu Menü > CMPs > TVWenn Sie den Menüpunkt „TV“ nicht sehen, wenden Sie sich bitte an Ihren Account Manager, um Ihr Konto zu aktualisieren.

TV-API aktivieren

Um die API nutzen zu können, müssen Sie ein CMP in Ihrem consentmanager Konto und aktivieren Sie die TV-API. Die CMP verwendet dieselben Einstellungen wie in einer Webumgebung. Das bedeutet, dass Sie die allgemeinen Einstellungen der CMP festlegen und Zwecke und Anbieter hinzufügen müssen. Navigieren Sie anschließend zu Menü > CMPs > TV und aktivieren Sie den Schalter auf TV-API aktivieren.

Sobald die API aktiviert ist, wird der API-Endpunkt unterhalb des Schalters angezeigt. Kopieren Sie die Endpunkt-URL zur weiteren Verwendung in Ihrer Implementierung.

Hinweis: Sobald die API aktiviert ist, dauert bis zu 1 Stunde bevor der API-Endpunkt nutzbar wird. Bitte beachten Sie auch, dass Änderungen an den CMP- oder Design-Einstellungen nur täglich innerhalb der TV-API.

API-Flow

Um die Zustimmungsschnittstelle in eine App zu implementieren, ruft der App-Entwickler die TV-API auf, um zu erfahren, ob der Zustimmungsbildschirm diesem bestimmten Benutzer angezeigt werden soll oder nicht. Die API enthält außerdem Informationen zu Farben und Texten, die dem Endbenutzer angezeigt werden sollen, sowie zu den Schaltflächen und Links, die angezeigt werden sollen. Sobald der Endbenutzer eine Auswahl trifft, informiert die App den consentmanager Das System informiert das TV-System über die TV-API über diese Auswahl und erhält im Gegenzug die Einwilligungsdaten (z. B. IAB TCF-Einwilligungszeichenfolge, IAB GPP-Zeichenfolge, Liste der aktivierten Anbieter, Liste der Zwecke usw.). Die App kann diese Einwilligungsdaten dann verwenden, um Datenverarbeitungsaktivitäten zu bestimmen oder sie an Dritte weiterzugeben (z. B. die IAB TCF-Einwilligungszeichenfolge).

Detailliertes Flussdiagramm

Nachfolgend finden Sie das detaillierte Flussdiagramm zur Implementierung der TV-API. Die Schritte sind wie folgt:

1. App-Start
2. App ruft Daten aus dem Einwilligungsspeicher ab (sofern vorhanden)
3. App ruft TV-API-Endpunkt „AppStart“ auf und übergibt vorhandene Zustimmungszeichenfolge
4. Die TV-API antwortet mit „displayLayer“, das auf „true“ oder „false“ gesetzt ist, um anzuzeigen, dass die Zustimmungsschnittstelle angezeigt werden soll
5. (Wenn displayLayer = true) Die App zeigt die Zustimmungsschnittstelle unter Verwendung der Informationen aus der TV-API an
6. Benutzer klickt auf „Akzeptieren“: App ruft TV-API-Endpunkt „Feedback“ zum Akzeptieren auf
   -> App speichert Einwilligungsdaten und fährt wie gewohnt fort
7. Benutzer klickt auf Ablehnen: App ruft TV-API-Endpunkt „Feedback“ zur Ablehnung auf
   --> App speichert Einwilligungsdaten und fährt wie gewohnt fort
8. Benutzer klickt auf Einstellungen: App zeigt QR-Code an
9. Die App ruft alle 3 Sekunden den TV-API-Endpunkt „QR-Status“ zur Statusaktualisierung auf
10. Sobald der QR-Status „abgeschlossen“ ist (oder der Benutzer auf die Schaltfläche „Zurück“ klickt), speichert die App die Zustimmungsdaten 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 Zustimmungsoberfläche angezeigt werden soll oder nicht
   Dies wird durch die Eigenschaft „displayLayer“ mit dem Wert „true“ (Anzeige der Zustimmungsschnittstelle) oder „false“ (keine Anzeige der Zustimmungsschnittstelle erforderlich) signalisiert.
   
   
2. Welches Styling soll verwendet werden, falls Sie die Zustimmungsoberfläche anzeigen müssen/möchten
   Dies wird durch die Eigenschaften „Anzeige“ signalisiert.

Aufrufen des AppStart-Endpunkts

Beim Aufruf des AppStart-Endpunkts sollten Sie die URL verwenden, die Ihnen in Ihrem consentmanager Login-Bereich. Zusätzlich sollten Sie die URL um folgende Parameter erweitern:

AppStart-Endpunktantwort

Die API-Antwort ist ein JSON-codiertes 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 Zustimmungsschnittstelle

Insbesondere bei der Verwendung von Industriestandards wie dem IAB TCF oder IAB GPP, consentmanager ist durch die Politik verpflichtet, sicherzustellen, dass bestimmte Standards von seinen Kunden eingehalten werden. Wir sollen Fordern Sie daher alle Clients auf, die über den AppStart-Endpunkt bereitgestellten Informationen zu verwenden, um das Design der Zustimmungsschnittstelle zu erstellen.

Wichtig: Um sicherzustellen, dass alle Regeln eingehalten werden, erfordern Alle Kunden sollen einen Beispiel-Screenshot der von ihnen erstellten Zustimmungsschnittstelle zur Genehmigung einreichen.

IAB TCF- und GPP-Konformität

Um die Einhaltung von IAB TCF und GPP sicherzustellen, müssen wir von allen Clients verlangen, die über den AppStart-Endpunkt bereitgestellten Elemente zu verwenden, und zwar:

1. Die Einwilligungsoberfläche 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 anderweitig unsichtbar sein.
2. Die Zustimmungsschnittstelle muss die von der API angegebenen Schaltflächen und den von der API bereitgestellten Beschriftungstext anzeigen. Schaltflächen müssen sofort sichtbar sein und dürfen nicht verdeckt werden.
3. Die Einwilligungsschnittstelle muss die von der API bereitgestellten Links anzeigen. Die Links müssen für den Client zugänglich sein, müssen aber nicht sofort sichtbar sein. Wir empfehlen jedoch, alle Links stets sichtbar zu machen.
4. Die Zustimmungsoberfläche muss die von der API vorgegebenen Farben verwenden. Ist dies aufgrund von Gerätebeschränkungen nicht möglich, muss die Zustimmungsoberfläche so gestaltet sein, dass alle Schaltflächen die gleiche Bedeutung haben.

Feedback-Endpunkt

Die Antwort des AppStart-Endpunkts enthält zwei URLs: „feedback.accept“ und „feedback.reject“. Diese URLs werden von der App aufgerufen, sobald der Benutzer die Datenschutzeinstellungen akzeptiert oder ablehnt.

Aufrufen des Feedback-Endpunkts

Die Feedback-Endpunkt-URLs sind bereits durch den AppStart-Endpunkt-API-Aufruf vorkonfiguriert und müssen nicht geändert oder ergänzt werden. Bitte rufen Sie die korrekte URL entsprechend der Benutzerauswahl auf.

Feedback-Endpunktantwort

Die API-Antwort ist ein JSON-codiertes 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-Endpunkt

Klickt der Nutzer auf „Einstellungen“, zeigt die App einen zweiten Zustimmungsbildschirm mit einem QR-Code (und optional einer URL) an. Der Nutzer scannt anschließend den QR-Code und kann seine Datenschutzeinstellungen auf seinem Mobiltelefon vornehmen. Währenddessen prüft die App den aktuellen Status des Vorgangs.

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

Aufrufen des Feedback-Endpunkts

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

QR-Code-Endpunktantwort

Die API-Antwort ist ein JSON-codiertes 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 Implementierungsinformationen

Einwilligungsspeicherung

Sobald der Benutzer eine Auswahl getroffen hat oder der QR-Code-Prozess 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 von einem Aufruf einer externen API abhängig ist, empfehlen wir verschiedene Strategien zur Fehlerbehandlung, um Probleme und eine schlechte Benutzererfahrung zu vermeiden:

• API-Fehler
  Falls eine API einen unerwarteten HTTP-Statuscode (z. B. 4xx, 5xx oder 6xx) zurückgibt, behandelt die App dies als Fehler. Die App sollte auf einen Standardzustand oder eine Standardlogik zurückgreifen und die nächsten Schritte im Prozess überspringen. Wird der HTTP-Statuscode 3xx gesendet oder anderweitig eine Standortänderung signalisiert, folgt die App der signalisierten URL (Hinweis: Wenden Sie eine Maximalfolgeregel an, um Endlosschleifen zu vermeiden).
  
  
• Timeouts
  Alle API-Aufrufe müssen ein maximales Timeout haben, z. B. 15 Sekunden. Reagiert die API innerhalb dieser Zeitspanne nicht, gilt sie als offline. 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 Probleme bereiten, wenn Zertifikatsversionen oder Verschlüsselungsmethoden nicht mehr unterstützt werden. In diesem Fall können App-Entwickler die API-Endpunkte über http statt https aufrufen.
  
  
• Analysefehler
  Alle API-Endpunkte geben JSON-Objekte als UTF-8-codierte Zeichenfolgen zurück. Beim Parsen der Zeichenfolge sollte die App überprüfen, ob die Analyse 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.
  • Überprüfen Sie, ob der zurückgegebene Wert einer Eigenschaft vom erwarteten Datentyp ist (z. B. Zeichenfolge, Bool oder Ganzzahl).
  • Seien Sie flexibel bei der Objektstruktur. Manche Objekte haben eine dynamische Struktur und können mit mehr oder weniger Eigenschaften auftreten. Kennt eine App eine Eigenschaft nicht, ignoriert sie diese.
    
    
• QR-Code-Statusfehler
  In Fällen, in denen der QR-Code-Status-Endpunkt den Status „Fehler“ zurückgibt, sollte die App die Einwilligungserfassung abbrechen und wie gewohnt fortfahren.
  
  
• QR-Code aufgegeben

Wird der QR-Code angezeigt, aber über längere Zeit keine Statusänderung beobachtet, kehrt die App zur ursprünglichen Zustimmungsoberfläche (erster Bildschirm) zurück und ermöglicht dem Benutzer eine erneute Auswahl. Wir empfehlen eine maximale Wartezeit von 5 Minuten, bevor zum ersten Bildschirm zurückgekehrt wird.

Versionsverwaltung

Die API-Versionen werden über die AppStart-Endpunkt-URL verwaltet. Im Falle einer API-Änderung aktualisieren wir die AppStart-Endpunkt-URL auf eine neue Version, damit mehrere Versionen gleichzeitig aktiv sein können.