[CTV-API] Intégration - Consentmanager Staging

Aperçu général

L'objectif de l'API est de permettre aux clients de développer leur propre interface de consentement lorsque les SDK fournis par ConsentManager ne sont pas suffisants. L'API permettra donc au client de créer sa propre interface graphique à partir des informations fournies par l'API. De plus, l'API permettra au client d'utiliser des normes industrielles telles que l'IAB TCF ou l'IAB GPP sans avoir à implémenter ses propres encodeurs/décodeurs.

Mise en œuvre

La mise en œuvre comprend quatre parties :

API
TV Elle permet d'interroger les informations relatives au texte, aux couleurs, aux boutons et aux liens qui doivent s'afficher dans l'interface de consentement.
L'API TV est fournie par consentmanager.
Interface
de consentement Elle affiche le message de consentement pour permettre à l'utilisateur final de faire un choix.
Elle doit être créée par le développeur de l'application.
Stockage
des consentements Une fois qu'un choix a été fait, le système de stockage des consentements enregistrera ces choix afin d'utiliser les informations en cas de besoin.
Ce système doit être créé par le développeur de l'application.
Code QR / Interface
de paramètres personnalisés Si l'utilisateur final souhaite faire des choix personnalisés autres que « accepter » ou « refuser », l'application peut afficher un code QR spécifique que l'utilisateur final peut scanner avec son téléphone portable. L'utilisateur final sera redirigé vers un site web où il pourra faire ses choix. Une fois cela fait, les choix sont renvoyés à l'appareil TV via l'API TV et l'utilisateur final peut continuer à utiliser l'application.
Ce service est fourni par consentmanager.

Contraintes

Étant donné que le client mettra en place sa propre interface, l'API n'offre pas toutes les fonctionnalités disponibles dans le cadre d'une intégration web ou d'application classique. Entre autres, les fonctionnalités suivantes ne font pas partie de l'API (entre autres) :

Paramètres CMP

· Intégrations (par ex. Adobe, Awin, etracker, etc.)

· API de confidentialité (DNT, GPC, ADPC, …)

· Blocage automatique

· Vérification de l'âge

· Fonctionnalités de rapport réduites

Paramètres de conception

· Taille et position de la boîte

· Taille et police de caractères

· Boutons bascules / cases à cocher sur le premier niveau

· Icônes pour les fonctions, boutons et liens

· Prise en charge des WCAG

· Logique de comportement et effets

Remarque : les paramètres mentionnés ci-dessus ne sont pas envoyés via l'API, mais peuvent être mis en œuvre manuellement par le développeur de l'application.

Aucune restriction concernant les paramètres

Outre les limitations mentionnées ci-dessus, il existe encore de nombreuses fonctionnalités qui font partie de l'API (lorsqu'elle est entièrement implémentée dans votre application) et qui peuvent être utilisées comme d'habitude. Il s'agit notamment des suivantes :

Adaptation automatique des textes à la langue de l'utilisateur
Affichage de la couche de consentement dans les couleurs définies via CMP / Design
Prise en charge des normes IAB TCF, IAB GPP et du mode de consentement de Google
Tests A/B et apprentissage automatique de différents designs
Ciblage des designs vers les utilisateurs finaux en fonction de la langue, du pays ou d'autres attributs
Rapports (limités) sur les utilisateurs, les écrans de consentement affichés et les choix effectués

Configuration

Prérequis

Pour utiliser l'API, vous devez disposer d'un compte ConsentManager avec la fonctionnalité « TV SDK » activée (généralement incluse dans les forfaits supérieurs). Vous pouvez vérifier si cette fonctionnalité est incluse en vous connectant à votre compte et en accédant à Menu > CMP > TV. Si vous ne voyez pas l'option de menu « TV », veuillez contacter votre gestionnaire de compte pour mettre à niveau votre compte.

Activer l'API TV

Pour commencer à utiliser l'API, vous devrez créer un CMP dans votre compte ConsentManager et activer l'API TV. La CMP doit suivre les mêmes paramètres que ceux que vous utiliseriez normalement pour un environnement web, ce qui signifie que vous devrez définir les paramètres généraux de la CMP et ajouter des finalités et des fournisseurs. Une fois cela fait, accédez à Menu > CMP > TV et activez le bouton « Activer l'API TV ».

Une fois l'API activée, vous verrez le point de terminaison de l'API sous le bouton bascule. Copiez l'URL du point de terminaison pour l'utiliser ultérieurement dans votre implémentation.

Remarque : une fois l'API activée, il faudra compter jusqu'à 1 heure avant que le point de terminaison API ne soit utilisable. Veuillez également noter que les modifications apportées aux paramètres CMP ou de conception ne seront prises en compte que quotidiennement au sein de l'API TV.

API-Flow

Pour intégrer l'interface de consentement dans une application, le développeur de l'application appellera l'API TV afin de savoir si l'écran de consentement doit être affiché ou non pour cet utilisateur spécifique. L'API contiendra également des informations sur les couleurs et les textes à présenter à l'utilisateur final, ainsi que sur les boutons et les liens à afficher. Une fois que l'utilisateur final a fait son choix, l'application informera le système ConsentManager via l'API TV de ce choix et recevra en retour les données de consentement (par exemple, la chaîne de consentement IAB TCF, la chaîne IAB GPP, la liste des fournisseurs activés, la liste des finalités, etc.). L'application peut ensuite utiliser ces données de consentement pour déterminer les activités de traitement des données ou les fournir à des tiers (par exemple, la chaîne de consentement IAB TCF).

Organigramme détaillé

Vous trouverez ci-dessous l'organigramme détaillé de la mise en œuvre de l'API TV. Les étapes sont les suivantes :

Lancement de l'application
L'application récupère les données du magasin de consentements (le cas échéant)
L'application appelle le point de terminaison de l'API TV « AppStart » et transmet la chaîne de consentement existante
L'API TV répond avec « displayLayer » défini sur « true » ou « false » pour indiquer que l'interface de consentement doit s'afficher
(Si displayLayer = true) L'application affiche l'interface de consentement en utilisant les informations provenant de l'API TV
L'utilisateur clique sur « Accepter » : l'application appelle le point de terminaison « Feedback » de l'API TV pour
l'acceptation –> L'application enregistre les données de consentement et continue normalement
L'utilisateur clique sur « Refuser » : l'application appelle le point de terminaison « Feedback » de l'API TV pour le
refus –> L'application enregistre les données de consentement et continue normalement
L'utilisateur clique sur Paramètres : l'application affiche un code QR
L'application appelle le point de terminaison de l'API TV « QR-Status » toutes les 3 secondes pour une mise à jour de l'état
Une fois que le statut du QR code est « terminé » (ou que l'utilisateur clique sur le bouton « Retour »), l'application enregistre les données de consentement et continue normalement.

AppStart Endpoint

L'URL du point de terminaison AppStart se trouve dans votre espace de connexion ConsentManager (voir la section « Configuration » ci-dessus). Le point de terminaison renverra un objet JSON et vous fournira deux informations :

Affichage
ou non de l'interface de consentement. Ceci est indiqué par la propriété « displayLayer » avec la valeur « true » (afficher l'interface de consentement) ou « false » (pas besoin d'afficher l'interface de consentement).
Quel style faut-il utiliser si vous devez/souhaitez afficher l'interface
de consentement ? Cela est indiqué par les propriétés « display ».

Appel du point de terminaison AppStart

Lorsque vous appelez l'AppStart Endpoint, vous devez utiliser l'URL qui vous a été fournie dans votre espace de connexion ConsentManager. De plus, vous devez compléter l'URL en y ajoutant les paramètres suivants :

Paramètre	Description
`&l=…`	(facultatif, recommandé) Langue souhaitée pour l'affichage. Par exemple : &l=DE ou &l=EN-US. L'API renverra les textes dans cette langue.
`&appid=…`	(facultatif, recommandé) Identifiant de l'application. Par exemple : &appid=123456 ou &appid=my-app-name
`&cs=…`	(facultatif, obligatoire s'il est présent) La chaîne de consentement enregistrée correspondant au dernier choix de l'utilisateur. La chaîne de consentement est transmise à l'application par : a) le point de terminaison Feedback sous la propriété « consentstring » ou b) le point de terminaison QR-Status sous la propriété « feedbackobject.consentstring »
`&ip=…`	(facultatif) Adresse IP de l'utilisateur à utiliser à des fins de géolocalisation. Si aucune adresse IP n'est transmise, l'adresse IP de la source de la requête est utilisée. Par exemple : &ip=123.123.123.123

Réponse de l'endpoint AppStart

La réponse de l'API sera un objet encodé en JSON au format suivant :

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

Mise en forme de l'interface de consentement

En particulier lors de l'utilisation de normes sectorielles telles que l'IAB TCF ou l'IAB GPP, consentmanager est tenu, par sa politique, de veiller à ce que certaines normes soient respectées par ses clients. Nous devons donc exiger de tous nos clients qu'ils utilisent les informations fournies via l'AppStart Endpoint pour concevoir l'interface de consentement.

Important : afin de garantir le respect de toutes les règles, nous demandons à tous nos clients de nous soumettre, pour validation, une capture d'écran de l'interface de consentement qu'ils ont créée.

Conformité IAB TCF & GPP

Afin de garantir la conformité aux normes IAB TCF et GPP, nous devons exiger de tous nos clients qu'ils utilisent les éléments fournis via l'AppStart Endpoint, à savoir :

L'interface de consentement doit afficher un titre et un texte sur le premier écran. Le titre et le texte doivent être extraits de l'API et affichés dans leur intégralité. Ils ne doivent pas être masqués, raccourcis ou rendus invisibles de quelque manière que ce soit.
L'interface de consentement doit afficher les boutons indiqués par l'API et avec le texte de libellé fourni par l'API. Les boutons doivent être immédiatement visibles et ne doivent pas être masqués.
L'interface de consentement doit afficher les liens indiqués par l'API. Les liens doivent être accessibles par le client, mais ne doivent pas nécessairement être immédiatement visibles. Quoi qu'il en soit, nous recommandons de toujours rendre tous les liens visibles.
L'interface de consentement doit utiliser les couleurs indiquées par l'API. Si cela n'est pas possible en raison des restrictions de l'appareil, l'interface de consentement doit être conçue de manière à garantir que tous les boutons aient la même importance.

Point de contact pour les commentaires

La réponse de l'AppStart Endpoint contiendra deux URL via « feedback.accept » et « feedback.reject ». Ces URL doivent être appelées par l'application une fois que l'utilisateur a choisi d'accepter ou de refuser les paramètres de confidentialité.

Appel du point de terminaison de feedback

Les URL des points de terminaison de feedback sont déjà pré-construites par l'appel API du point de terminaison AppStart et n'ont pas besoin d'être modifiées ou complétées. Veuillez appeler l'URL correcte correspondant au choix de l'utilisateur.

Réponse du point de terminaison de retour d'information

La réponse de l'API sera un objet encodé en JSON au format suivant :

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

Point de destination du code QR

Si l'utilisateur clique sur « Paramètres », l'application doit afficher un deuxième écran de consentement comportant un code QR (et une URL facultative). L'utilisateur scannera alors le code QR et poursuivra la configuration de ses préférences de confidentialité sur son téléphone portable. Pendant ce temps, l'application doit vérifier l'état actuel de la procédure.

Pour cela, la réponse de l'AppStart Endpoint contiendra une URL via « customsettings.statusurl ». Cette URL doit être appelée par l'application dès que le code QR s'affiche à l'écran. Nous recommandons d'appeler l'URL toutes les 3 secondes afin de vérifier la présence de mises à jour.

Appel du point de terminaison de feedback

L'URL de destination du code QR est déjà pré-générée par l'appel API AppStart Endpoint et n'a pas besoin d'être modifiée ou complétée. Veuillez effectuer un appel toutes les 3 secondes pendant que l'utilisateur fait ses choix.

Réponse du point de terminaison du code QR

La réponse de l'API sera un objet encodé en JSON au format suivant :

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

Autres informations relatives à la mise en œuvre

Stockage des consentements

Chaque fois que l'utilisateur fait un choix ou que le processus du code QR se termine, l'API renvoie l'objet de retour d'information avec tous les détails. Nous recommandons aux développeurs d'applications de stocker l'objet complet.

Gestion des erreurs

Étant donné que l'application dépend d'un appel à une API externe, nous recommandons diverses stratégies de gestion des erreurs afin d'éviter les problèmes et une mauvaise expérience utilisateur :

Erreurs
API Si une API renvoie un code d'état HTTP inattendu (par exemple 4xx, 5xx ou 6xx), l'application doit traiter cela comme une erreur. L'application doit revenir à un état ou à une logique par défaut et ignorer les étapes suivantes du processus. Dans les cas où un code d'état HTTP 3xx est envoyé ou qu'un changement d'emplacement est signalé, l'application doit suivre l'URL indiquée (Remarque : appliquez une règle de suivi maximal pour éviter les boucles infinies).
Délais d'attente
Tous les appels API doivent avoir un délai d'attente maximal, par exemple 15 secondes. Si l'API ne répond pas dans ce délai, elle doit être considérée comme hors ligne. L'application doit alors revenir à un état ou à une logique par défaut et ignorer les étapes suivantes du processus.
Validation
SSL La validation SSL peut poser des problèmes, en particulier sur les appareils plus anciens, lorsque les versions de certificats ou les méthodes de chiffrement ne sont plus prises en charge. Si tel est le cas, les développeurs d'applications peuvent appeler les points de terminaison de l'API via http au lieu de https.
Erreurs
d'analyse Tous les points de terminaison de l'API renvoient des objets JSON sous forme de chaînes encodées en UTF-8. Lors de l'analyse de la chaîne, l'application doit vérifier que l'analyse s'est déroulée comme prévu. De plus, l'application doit :
- Considérez toutes les propriétés de tous les objets comme facultatives et vérifiez toujours si une propriété existe avant d'y accéder.
- Vérifiez si la valeur renvoyée par une propriété est du type de données attendu (par exemple, chaîne de caractères, booléen ou entier).
- Faites preuve de souplesse quant à la structure des objets. Certains objets ont une structure dynamique et peuvent comporter plus ou moins de propriétés. Si une application ne reconnaît pas une propriété, elle doit l'ignorer.
Erreur
de statut du code QR Lorsque l'endpoint de statut du code QR renvoie status=error, l'application doit interrompre la collecte du consentement et reprendre son fonctionnement normal.
Code QR abandonné

Dans les cas où le code QR est affiché mais qu'aucun changement de statut n'est observé pendant un certain temps, l'application doit revenir à l'interface de consentement initiale (premier écran) et permettre à l'utilisateur de faire un nouveau choix. Nous recommandons un délai d'attente maximal de 5 minutes avant de revenir au premier écran.

Gestion des versions

Les versions de l'API sont gérées via l'URL du point de terminaison AppStart. En cas de modification de l'API, nous mettrons à jour l'URL du point de terminaison AppStart vers une nouvelle version afin de permettre l'activation simultanée de plusieurs versions.