[CTV-API] Intégration

Aperçu général

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

Implantation

La mise en œuvre comprend quatre parties :

1. API TV
   Il permet d'interroger des informations sur le texte, les couleurs, les boutons et les liens qui doivent être affichés dans l'interface de consentement.
   L'API TV est fournie par consentmanager.
   
   
2. Interface de consentement
   Il affiche le message de consentement pour permettre à l'utilisateur final de faire un choix.
   Ceci doit être créé par le développeur de l'application.
   
   
3. Stockage du consentement
   Une fois qu'un choix est fait, le stockage du consentement stockera ces choix pour utiliser les informations lorsque cela est nécessaire.
   Ceci doit être créé par le développeur de l'application.
   
   
4. Interface QR-Code / Paramètres personnalisés
   Si l'utilisateur final souhaite personnaliser ses choix, outre l'acceptation ou le refus, l'application peut afficher un QR-code spécifique qu'il peut scanner avec son téléphone portable. Il sera alors redirigé vers un site web où il pourra faire ses choix. Une fois ces choix effectués, ils sont renvoyés au téléviseur via l'API TV et l'utilisateur peut continuer à utiliser l'application.
   Ceci est fourni par consentmanager.

Limites

Étant donné que le client implémente sa propre interface, l'API n'offre pas toutes les fonctionnalités d'une intégration web ou applicative classique. Parmi les fonctionnalités suivantes, on peut citer :

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

Aucune limitation sur les paramètres

Outre les limitations mentionnées ci-dessus, de nombreuses fonctionnalités de l'API (une fois pleinement implémentées dans votre application) peuvent être utilisées normalement. Parmi celles-ci, on peut citer :

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

installation

Pré-requis :

Pour utiliser l'API, vous devez disposer d'un consentmanager compte avec la fonctionnalité « SDK TV » activée (généralement incluse dans les forfaits supérieurs). Pour vérifier si cette fonctionnalité est incluse, connectez-vous à votre compte et accédez à Menu > CMP > TVSi vous ne voyez pas l’élément 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 consentmanager et activez l'API TV. La CMP doit suivre les mêmes paramètres que pour un environnement web. Vous devrez donc définir les paramètres généraux de la CMP et ajouter des objectifs et des fournisseurs. Une fois cela fait, accédez à Menu > CMP > TV et activez la bascule sur Activer l'API TV.

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

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

API-Flow

Pour implémenter l'interface de consentement dans une application, le développeur appelle l'API TV pour savoir si l'écran de consentement doit être affiché ou non à l'utilisateur. L'API contient également des informations sur les couleurs et les textes à afficher, ainsi que sur les boutons et les liens à afficher. Une fois le choix effectué, l'application l'informe. consentmanager Le système informe le client de ce choix via l'API TV et reçoit 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 transmettre à des tiers (par exemple, la chaîne de consentement IAB TCF).

Organigramme détaillé

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

1. Démarrage de l'application
2. L'application récupère les données du magasin de consentement (le cas échéant)
3. L'application appelle le point de terminaison de l'API TV « AppStart » et transmet la chaîne de consentement existante
4. L'API TV répond avec « displayLayer » défini sur « true » ou « false » pour indiquer que l'interface de consentement doit être affichée
5. (Si displayLayer = true) L'application affiche l'interface de consentement à l'aide des informations de l'API TV
6. L'utilisateur clique sur Accepter : l'application appelle le point de terminaison de l'API TV « Feedback » pour accepter
   -> L'application stocke les données de consentement et continue comme d'habitude
7. L'utilisateur clique sur Rejeter : l'application appelle le point de terminaison de l'API TV « Feedback » pour le rejeter
   --> L'application stocke les données de consentement et continue comme d'habitude
8. L'utilisateur clique sur Paramètres : l'application affiche le code QR
9. L'application appelle le point de terminaison de l'API TV « QR-Status » toutes les 3 secondes pour la mise à jour du statut
10. Une fois que le statut QR est « terminé » (ou que l'utilisateur clique sur le bouton « retour »), l'application stocke les données de consentement et continue normalement

Point de terminaison AppStart

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

1. Si l'interface de consentement doit être affichée ou non
   Ceci est signalé par la propriété « displayLayer » avec la valeur « true » (afficher l'interface de consentement) ou « false » (pas besoin d'afficher l'interface de consentement).
   
   
2. Quel style doit être utilisé, au cas où vous devez/voulez afficher l'interface de consentement
   Ceci est signalé par les propriétés « affichage »

Appel du point de terminaison AppStart

Lorsque vous appelez le point de terminaison AppStart, vous devez utiliser l'URL qui vous est fournie dans votre consentmanager Zone de connexion. Vous devez également étendre l'URL en ajoutant les paramètres suivants :

Réponse du point de terminaison AppStart

La réponse de l'API sera un objet codé 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
 }
}

Styliser l'interface de consentement

En particulier lors de l’utilisation de normes industrielles telles que l’IAB TCF ou l’IAB GPP, consentmanager est tenue, par sa politique, de garantir le respect de certaines normes par ses clients. doit par conséquent, tous les clients doivent utiliser les informations fournies via le point de terminaison AppStart pour composer la conception de l'interface de consentement.

Important: Afin de garantir que toutes les règles soient respectées, nous exigent tous les clients doivent soumettre un exemple de capture d'écran de l'interface de consentement qu'ils ont créée pour approbation.

Conformité IAB TCF et GPP

Afin de garantir la conformité IAB TCF et GPP, nous devons exiger de tous les clients qu'ils utilisent les éléments fournis via le point de terminaison AppStart, en particulier :

1. 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 intégralement. Ils ne doivent pas être masqués, raccourcis ou invisibles.
2. L'interface de consentement doit afficher les boutons indiqués par l'API et le texte d'étiquette fourni par l'API. Les boutons doivent être visibles immédiatement et ne doivent pas être masqués.
3. L'interface de consentement doit afficher les liens indiqués par l'API. Ces liens doivent être accessibles au client, mais ne doivent pas nécessairement être immédiatement visibles. Nous recommandons toutefois de toujours rendre tous les liens visibles.
4. 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 à ce que tous les boutons aient la même importance.

Point de terminaison des commentaires

La réponse du point de terminaison AppStart contiendra deux URL : « feedback.accept » et « feedback.reject ». Ces URL seront appelées par l'application lorsque l'utilisateur choisira d'accepter ou de refuser les paramètres de confidentialité.

Appel du point de terminaison de rétroaction

Les URL des points de terminaison de commentaires sont pré-construites par l'appel d'API AppStart Endpoint et n'ont pas besoin d'être modifiées ni ajoutées. Veuillez utiliser l'URL appropriée correspondant au choix de l'utilisateur.

Réponse du point de terminaison de rétroaction

La réponse de l'API sera un objet codé 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 terminaison du code QR

Si l'utilisateur clique sur « Paramètres », l'application affichera un deuxième écran de consentement contenant un code QR (et une URL facultative). L'utilisateur pourra alors scanner le code QR et poursuivre ses choix de confidentialité sur son téléphone mobile. Pendant ce temps, l'application vérifiera l'état d'avancement de la procédure.

Pour cela, la réponse du point de terminaison AppStart contiendra une URL via « customsettings.statusurl ». Cette URL sera appelée par l'application une fois le QR-code affiché. Nous recommandons d'appeler l'URL toutes les 3 secondes afin de vérifier les mises à jour.

Appel du point de terminaison de rétroaction

L'URL du point de terminaison du code QR est pré-construite par l'appel d'API AppStart Endpoint et n'a pas besoin d'être modifiée ni ajoutée. Veuillez l'appeler toutes les 3 secondes pendant que l'utilisateur effectue ses choix.

Réponse du point de terminaison du code QR

La réponse de l'API sera un objet codé 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 de mise en œuvre

Stockage du consentement

Dès que l'utilisateur effectue un choix ou que le processus de création du QR-Code est terminé, l'API renvoie l'objet de commentaires contenant tous les détails. Nous recommandons aux développeurs d'applications de stocker l'objet complet.

La gestion des erreurs

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

• Erreurs d'API
  Si une API renvoie un code d'état HTTP inattendu (par exemple 4xx, 5xx ou 6xx), l'application doit le traiter comme une erreur. Elle doit revenir à un état ou une logique par défaut et ignorer les étapes suivantes du processus. Si le code d'état HTTP 3xx est envoyé ou qu'un changement d'emplacement est signalé, l'application doit suivre l'URL signalée (Remarque : appliquez une règle de suivi maximal pour éviter les boucles infinies).
  
  
• Délais d'attente
  Tous les appels d'API doivent avoir un délai d'expiration 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 revenir à un état ou une logique par défaut et ignorer les étapes suivantes du processus.
  
  
• Validation SSL
  La validation SSL peut poser problème, notamment sur les appareils plus anciens, lorsque les versions de certificat ou les méthodes de chiffrement ne sont plus prises en charge. Dans ce cas, les développeurs d'applications peuvent appeler les points de terminaison de l'API via http plutôt que 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 a fonctionné comme prévu. De plus, l'application doit :
  • Traitez 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 d'une propriété est du type de données attendu (par exemple, chaîne, booléen ou entier).
  • Soyez flexible sur la structure des objets. Certains objets ont une structure dynamique et peuvent avoir plus ou moins de propriétés. Si une application ignore une propriété, elle doit l'ignorer.
    
    
• Erreur d'état du code QR
  Dans les cas où le point de terminaison d'état du code QR renvoie status=error, l'application doit interrompre la collecte du consentement et reprendre normalement.
  
  
• QR-Code abandonné

Si le QR-Code s'affiche sans changement de statut pendant un certain temps, l'application revient à l'interface de consentement initiale (premier écran) et permet à l'utilisateur de choisir à nouveau. Nous recommandons un délai d'attente maximal de 5 minutes avant de revenir au premier écran.

Gestion de version

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.