Descripción general

El objetivo de la API es permitir a los clientes desarrollar su propia interfaz de consentimiento para aquellos casos en los que los SDK proporcionados por ConsentManager no sean suficientes. Por lo tanto, la API permitirá al cliente crear su propia interfaz gráfica basándose en la información que proporciona la API. Además, la API permitirá al cliente utilizar estándares del sector, como el IAB TCF o el IAB GPP, sin necesidad de implementar sus propios codificadores/decodificadores.

Implementación

La implementación consta de cuatro partes:

1. API
   de TV Permite consultar información sobre el texto, los colores, los botones y los enlaces que deben mostrarse en la interfaz de consentimiento.
   La API de TV la proporciona consentmanager.
   
   
2. Interfaz
   de consentimiento Muestra el mensaje de consentimiento para permitir que el usuario final elija.
   Debe ser creada por el desarrollador de la aplicación.
   
   
3. Almacenamiento
   de consentimientos: una vez realizada una elección, el sistema de almacenamiento de consentimientos guardará estas elecciones para utilizar la información cuando sea necesario.
   Esto debe crearlo el desarrollador de la aplicación.
   
   
4. Código QR / Interfaz
   de configuración personalizada Si el usuario final desea realizar elecciones personalizadas además de aceptar o rechazar, la aplicación puede mostrar un código QR específico que el usuario final puede escanear con su teléfono móvil. El usuario final será redirigido a un sitio web donde podrá realizar sus elecciones. Una vez hecho esto, las elecciones se envían de vuelta al dispositivo de TV mediante la API de TV y el usuario final puede seguir utilizando la aplicación.
   Esto lo proporciona consentmanager.

Limitaciones

Dado que el cliente implementará su propia interfaz, la API no ofrece todas las funcionalidades en comparación con una integración web o de aplicación normal. Entre otras, las siguientes funciones no forman parte de la API (entre otras):

Configuración de CMP · Integraciones (p. ej., Adobe, Awin, etracker, etc.) · API de privacidad (DNT, GPC, ADPC, …) · Bloqueo automático · Verificación de edad · Funciones de informes reducidas

Configuración de diseño · Tamaño y posición del cuadro · Tamaño y tipo de letra · Botones de alternancia / Casillas de verificación en la primera capa · Iconos para fines, botones y enlaces · Compatibilidad con WCAG · Lógica de comportamiento y efectos

Sin limitaciones en la configuración

Además de las limitaciones mencionadas anteriormente, hay muchas otras funciones que forman parte de la API (cuando se implementa por completo en tu aplicación) y que se pueden utilizar como de costumbre. Entre otras, estas son:

• Adaptación automática de los textos al idioma del usuario
• Visualización de la capa de consentimiento con los colores establecidos a través de CMP / Diseño
• Compatibilidad con IAB TCF, IAB GPP y el modo de consentimiento de Google
• Pruebas A/B y aprendizaje automático de diferentes diseños
• Orientación de los diseños a los usuarios finales en función del idioma, el país u otros atributos
• Informes (limitados) de usuarios, pantallas de consentimiento mostradas y opciones

Configuración

Requisitos previos

Para utilizar la API, debes tener una cuenta de ConsentManager con la función «TV SDK» habilitada (normalmente incluida en los paquetes superiores). Puedes comprobar si la función está incluida iniciando sesión en tu cuenta y navegando a Menú > CMP > TV. Si no ves la opción de menú «TV», ponte en contacto con tu gestor de cuentas para actualizar tu cuenta.

Habilitar la API de TV

Para empezar a utilizar la API, tendrás que crear un CMP en tu cuenta de ConsentManager y habilitar la API de TV. La CMP debe seguir la misma configuración que seguirías normalmente para un entorno web, lo que significa que tendrás que configurar los ajustes generales de la CMP y añadir fines y proveedores. Una vez hecho esto, ve a Menú > CMP > TV y activa el interruptor de «Habilitar API de TV».

Una vez habilitada la API, verás el punto final de la API debajo del interruptor. Copia la URL del punto final para utilizarla posteriormente en tu implementación.

Flujo de la API

Para implementar la interfaz de consentimiento en una aplicación, el desarrollador de la aplicación llamará a la API de TV para recibir información sobre si se debe mostrar o no la pantalla de consentimiento a este usuario específico. La API también contendrá información sobre los colores y textos que se presentarán al usuario final, así como sobre qué botones y enlaces se mostrarán. Una vez que el usuario final haya tomado una decisión, la aplicación informará al sistema ConsentManager a través de la API de TV sobre dicha elección y, a cambio, recibirá los datos de consentimiento (por ejemplo, la cadena de consentimiento IAB TCF, la cadena IAB GPP, la lista de proveedores activados, la lista de fines, etc.). A continuación, la aplicación puede utilizar estos datos de consentimiento para determinar las actividades de tratamiento de datos o facilitarlos a terceros (por ejemplo, la cadena de consentimiento IAB TCF).

Diagrama de flujo detallado

A continuación encontrarás el diagrama de flujo detallado para la implementación de la API de TV. Los pasos son los siguientes:

1. Inicio de la aplicación
2. La aplicación recupera datos del almacén de consentimientos (si existe).
3. La aplicación llama al punto final de la API de TV «AppStart» y pasa la cadena de consentimiento existente
4. La API de TV responde con «displayLayer» establecido en «true» o «false» para indicar que se mostrará la interfaz de consentimiento.
5. (Si displayLayer = true) La aplicación muestra la interfaz de consentimiento utilizando la información de la API de TV
6. El usuario hace clic en «Aceptar»: la aplicación llama al punto final de la API de TV «Feedback» para la
   aceptación –> La aplicación almacena los datos de consentimiento y continúa con normalidad
7. El usuario hace clic en «Rechazar»: la aplicación llama al punto final de la API de TV «Feedback» para el rechazo
   –> La aplicación almacena los datos de consentimiento y continúa con normalidad
8. El usuario hace clic en «Configuración»: la aplicación muestra un código QR
9. La aplicación llama al punto final de la API de TV «QR-Status» cada 3 segundos para actualizar el estado
10. Una vez que el estado del QR es «finalizado» (o el usuario hace clic en el botón «Atrás»), la tienda de aplicaciones almacena los datos de consentimiento y continúa con normalidad.

AppStart Endpoint

La URL del punto final de AppStart se encuentra en tu área de inicio de sesión de ConsentManager (consulta la sección sobre configuración más arriba). El punto final devolverá un objeto JSON y te proporcionará dos datos:

1. Si se debe mostrar
   o no la interfaz de consentimiento. Esto se indica mediante la propiedad «displayLayer» con el valor «true» (mostrar la interfaz de consentimiento) o «false» (no es necesario mostrar la interfaz de consentimiento).
   
   
2. ¿Qué estilo se debe utilizar, en caso de que debas o quieras mostrar la interfaz
   de consentimiento? Esto se indica mediante la propiedad «display».

Llamada al punto final de AppStart

Al llamar al punto final de AppStart, debes utilizar la URL que se te ha facilitado en tu área de inicio de sesión de ConsentManager. Además, debes ampliar la URL añadiendo los siguientes parámetros:

Parámetro	Descripción
&l=…	(opcional, recomendado) Idioma deseado para la visualización. Por ejemplo, &l=DE o &l=EN-US. La API devolverá los textos en este idioma.
&appid=…	(opcional, recomendado) Identificador de la aplicación. Por ejemplo, &appid=123456 o &appid=my-app-name
&cs=…	(opcional, obligatorio si está presente) La cadena de consentimiento almacenada de la última elección del usuario. La cadena de consentimiento se pasa a la aplicación mediante: a) el punto final de retroalimentación bajo la propiedad «consentstring» o b) el punto final de estado del QR bajo la propiedad «feedbackobject.consentstring»
&ip=…	(opcional) Dirección IP del usuario que se utilizará con fines de geolocalización. Si no se pasa ninguna IP, se utiliza la IP del origen de la solicitud. Por ejemplo, &ip=123.123.123.123

Respuesta del punto final de AppStart

La respuesta de la API será un objeto codificado en JSON con el siguiente formato:

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

Diseño de la interfaz de consentimiento

Especialmente cuando se utilizan estándares del sector como el IAB TCF o el IAB GPP, consentmanager está obligado por política a garantizar que sus clientes cumplan con ciertos estándares. Por lo tanto, debemos exigir a todos los clientes que utilicen la información proporcionada a través del AppStart Endpoint para diseñar la interfaz de consentimiento.

Cumplimiento de IAB TCF y GPP

Para garantizar el cumplimiento de las normas IAB TCF y GPP, debemos exigir a todos los clientes que utilicen los elementos proporcionados a través del AppStart Endpoint, concretamente:

1. La interfaz de consentimiento debe mostrar un titular y un texto en la primera pantalla. El titular y el texto deben extraerse de la API y mostrarse íntegramente. No pueden quedar ocultos, abreviados ni invisibles de ningún otro modo.
2. La interfaz de consentimiento debe mostrar los botones indicados por la API y con el texto de etiqueta proporcionado por la API. Los botones deben ser visibles de inmediato y no pueden quedar ocultos.
3. La interfaz de consentimiento debe mostrar los enlaces indicados por la API. Los enlaces deben ser accesibles para el cliente, pero no es necesario que sean visibles de inmediato. De todos modos, recomendamos que todos los enlaces estén siempre visibles.
4. La interfaz de consentimiento deberá utilizar los colores indicados por la API. Si esto no fuera posible debido a restricciones del dispositivo, la interfaz de consentimiento deberá diseñarse de manera que se garantice que todos los botones tengan la misma importancia.

Punto final de comentarios

La respuesta del punto final de AppStart contendrá dos URL a través de «feedback.accept» y «feedback.reject». La aplicación deberá llamar a estas URL una vez que el usuario elija aceptar o rechazar la configuración de privacidad.

Llamada al punto final de retroalimentación

Las URL de los puntos finales de retroalimentación ya están preconfiguradas por la llamada a la API del punto final de AppStart y no es necesario modificarlas ni añadirles nada. Por favor, llama a la URL correcta correspondiente a la elección del usuario.

Respuesta del punto final de retroalimentación

La respuesta de la API será un objeto codificado en JSON con el siguiente formato:

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

Punto final del código QR

En caso de que el usuario haga clic en «Configuración», la aplicación mostrará una segunda pantalla de consentimiento con un código QR (y una URL opcional). A continuación, el usuario escaneará el código QR y continuará configurando sus preferencias de privacidad en su teléfono móvil. Mientras el usuario realiza esta acción, la aplicación comprobará el estado actual del procedimiento.

Para ello, la respuesta del punto final de AppStart contendrá una URL a través de «customsettings.statusurl». La aplicación deberá llamar a esta URL una vez que se muestre el código QR al usuario. Recomendamos llamar a la URL cada 3 segundos para comprobar si hay actualizaciones.

Llamada al punto final de retroalimentación

La URL del punto final del código QR ya está preconfigurada por la llamada a la API del punto final de AppStart y no es necesario modificarla ni añadirle nada. Por favor, realiza la llamada cada 3 segundos mientras el usuario realiza sus selecciones.

Respuesta del punto final del código QR

La respuesta de la API será un objeto codificado en JSON con el siguiente formato:

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

Otra información sobre la implementación

Almacenamiento de consentimientos

Cada vez que el usuario tome una decisión o finalice el proceso del código QR, la API devolverá el objeto de respuesta con todos los detalles. Recomendamos a los desarrolladores de aplicaciones que almacenen el objeto completo.

Gestión de errores

Dado que la aplicación depende de una llamada a una API externa, recomendamos varias estrategias de gestión de errores para evitar problemas y una mala experiencia de usuario:

• Errores
  de API En caso de que una API devuelva un código de estado HTTP inesperado (por ejemplo, 4xx, 5xx o 6xx), la aplicación deberá tratarlo como un error. La aplicación debe recurrir a un estado o lógica predeterminados y omitir los siguientes pasos del proceso. En los casos en que se envíe un código de estado HTTP 3xx o se señale un cambio de ubicación, la aplicación deberá seguir la URL señalada (Nota: aplica una regla de seguimiento máximo para evitar bucles infinitos).
  
  
• Tiempos de espera
  Todas las llamadas a la API deberán tener un tiempo de espera máximo, por ejemplo, 15 segundos. Si la API no responde en ese plazo, se considerará que está fuera de línea. La aplicación deberá recurrir a un estado o lógica predeterminados y omitir los siguientes pasos del proceso.
  
  
• Validación
  SSL Especialmente en dispositivos más antiguos, la validación SSL puede causar problemas cuando las versiones de los certificados o los métodos de cifrado ya no son compatibles. Si ese es el caso, los desarrolladores de aplicaciones pueden llamar a los puntos finales de la API a través de http en lugar de https.
  
  
• Errores
  de análisis Todos los puntos finales de la API devuelven objetos JSON como cadenas codificadas en UTF-8. Al analizar la cadena, la aplicación debe verificar que el análisis ha funcionado según lo esperado. Además, la aplicación deberá:
  • Trata todas las propiedades de todos los objetos como opcionales y comprueba siempre si una propiedad existe antes de acceder a ella.
  • Comprueba si el valor devuelto de una propiedad es del tipo de datos esperado (por ejemplo, cadena, booleano o entero).
  • Sé flexible con la estructura de los objetos. Algunos objetos tienen una estructura dinámica y pueden aparecer con más o menos propiedades. Si una aplicación no reconoce una propiedad, debe ignorarla.
    
    
• Error
  de estado del código QR En los casos en que el punto final de estado del código QR devuelva status=error, la aplicación debe abortar la recopilación del consentimiento y reanudarse con normalidad.
  
  
• Código QR abandonado

En los casos en que se muestre el código QR pero no se observe ningún cambio de estado durante un tiempo prolongado, la aplicación volverá a la interfaz de consentimiento inicial (primera pantalla) y permitirá al usuario volver a elegir. Recomendamos un tiempo de espera máximo de 5 minutos antes de volver a la primera pantalla.

Gestión de versiones

Las versiones de la API se gestionan a través de la URL del punto final de AppStart. En caso de que se produzca un cambio en la API, actualizaremos la URL del punto final de AppStart a una nueva versión para permitir que haya varias versiones activas al mismo tiempo.