Integración [CTV-API]

Visión general

El propósito de la API es permitir que los clientes desarrollen su propia interfaz de consentimiento para los casos en que los SDK proporcionados por consentmanager No son suficientes. Por lo tanto, la API permitirá al cliente crear su propia interfaz gráfica basándose en la información que proporciona. Además, la API permitirá al cliente utilizar estándares de la industria como IAB TCF o IAB GPP sin necesidad de implementar sus propios codificadores/decodificadores.

Implementación

La implementación consta de cuatro partes:

1. API de televisión
   Permite consultar información sobre el texto, colores, botones y enlaces que deben mostrarse en la interfaz de consentimiento.
   La API de TV es proporcionada por consentmanager.
   
   
2. Interfaz de consentimiento
   Muestra el mensaje de consentimiento para permitir que el usuario final tome una decisión.
   Esto lo debe crear el desarrollador de la aplicación.
   
   
3. Almacenamiento del consentimiento
   Una vez realizada una elección, el almacenamiento de consentimiento guardará estas elecciones para utilizar la información cuando sea necesario.
   Esto lo debe crear el desarrollador de la aplicación.
   
   
4. Interfaz de configuración personalizada/código QR
   Si el usuario final desea personalizar sus opciones además de aceptar o rechazar, la aplicación muestra un código QR específico que puede escanear con su teléfono móvil. Se le dirigirá a un sitio web donde podrá elegir sus opciones. Una vez seleccionadas, las opciones se envían al televisor mediante la API de TV y el usuario puede continuar usando la aplicación.
   Esto es proporcionado por consentmanager.

Limitaciones

Dado que el cliente implementará su propia interfaz, la API no ofrece la funcionalidad completa de una integración web o de aplicación normal. Entre otras, las siguientes funciones no forman parte de la API:

Nota: Las configuraciones mencionadas anteriormente no se envían a través de la API, sino que el desarrollador de la aplicación puede implementarlas manualmente.

Sin limitaciones en la configuración

Además de las limitaciones mencionadas, existen muchas características que forman parte de la API (una vez implementada completamente en la aplicación) y que pueden usarse con normalidad. Entre ellas, se encuentran:

• Alineación automática de textos al idioma del usuario
• Visualización de la capa de consentimiento en los colores establecidos mediante CMP/Diseño
• Compatibilidad con IAB TCF, IAB GPP y 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
• (limitado) Informes de usuarios, pantallas de consentimiento mostradas y opciones

Preparar

Requisitos previos

Para poder utilizar la API es necesario tener una consentmanager Cuenta con la función "SDK de TV" 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ú > CMPs > TVSi no ve la opción "TV" en el menú, comuníquese con su administrador de cuenta para actualizar su cuenta.

Habilitar API de TV

Para comenzar a utilizar la API necesitarás crear un CMP en tu consentmanager Cuenta y habilita la API de TV. El CMP deberá seguir la misma configuración que normalmente usarías para un entorno web, lo que significa que deberás configurar la configuración general del CMP y agregar propósitos y proveedores. Una vez hecho esto, navega a Menú > CMPs > TV y activa el interruptor Habilitar API de TV.

Una vez habilitada la API, verá el punto final de la API debajo del interruptor. Copie la URL del punto final para usarla en su implementación.

Nota: Una vez habilitada la API, Tomará hasta 1 hora antes de que el punto final de la API sea utilizable. Tenga en cuenta también que los cambios en la configuración de CMP o de diseño se reflejarán Sólo a diario dentro de la API de TV.

Flujo de API

Para implementar la interfaz de consentimiento en una aplicación, el desarrollador llamará a la API de TV para recibir información sobre si la pantalla de consentimiento debe mostrarse a este usuario específico. La API también contendrá información sobre los colores y textos que se mostrarán al usuario final, así como los botones y enlaces que se mostrarán. Una vez que el usuario final elija, la aplicación le informará. consentmanager El sistema informa al usuario sobre esta elección a través de la API de TV y, a cambio, recibe los datos de consentimiento (p. ej., la cadena de consentimiento TCF de IAB, la cadena GPP de IAB, la lista de proveedores activados, la lista de propósitos, etc.). La aplicación puede usar estos datos de consentimiento para determinar las actividades de procesamiento de datos o proporcionarlos a terceros (p. ej., la cadena de consentimiento TCF de IAB).

Diagrama de flujo detallado

A continuación, encontrará 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 consentimiento (si está presente)
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 "Comentarios" para aceptar
   -> La aplicación almacena datos de consentimiento y continúa normalmente.
7. El usuario hace clic en Rechazar: la aplicación llama al punto final de la API de TV "Comentarios" para rechazar
   --> La aplicación almacena datos de consentimiento y continúa normalmente
8. El usuario hace clic en Configuración: la aplicación muestra el 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 QR-Status está "finalizado" (o el usuario hace clic en el botón "atrás"), la aplicación almacena los datos de consentimiento y continúa normalmente.

Punto final de AppStart

La URL del punto final de AppStart se puede encontrar en su consentmanager Área de inicio de sesión (consulte la sección "Configuración" más arriba). El punto final devolverá un objeto JSON y le proporcionará dos datos:

1. Si se mostrará o no la interfaz de consentimiento
   Esto se indica mediante la propiedad “displayLayer” con el valor “true” (muestra la interfaz de consentimiento) o “false” (no es necesario mostrar la interfaz de consentimiento).
   
   
2. ¿Qué estilo se debe utilizar en caso de que se deba/quiera mostrar la interfaz de consentimiento?
   Esto se indica mediante las propiedades “display”

Llamar al punto final de AppStart

Al llamar al punto final de AppStart, debe utilizar la URL que se le proporcionó en su consentmanager Área de inicio de sesión. Además, debe ampliar la URL añadiendo los siguientes parámetros:

Respuesta del punto final de AppStart

La respuesta de la API será un objeto codificado JSON en 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
 }
}

Dar estilo a la interfaz de consentimiento

Especialmente cuando se utilizan estándares de la industria como IAB TCF o IAB GPP, consentmanager Por política, estamos obligados a garantizar que nuestros clientes cumplan con ciertos estándares. deben Por lo tanto, se requiere que todos los clientes utilicen la información suministrada a través del punto final AppStart para componer el diseño de la interfaz de consentimiento.

Importante: Para garantizar que se cumplan todas las normas, exigir Todos los clientes deben enviar una captura de pantalla de muestra de la interfaz de consentimiento que han creado para su aprobación.

Cumplimiento de IAB TCF y GPP

Para garantizar el cumplimiento de IAB TCF y GPP, debemos exigir a todos los clientes que utilicen los elementos suministrados a través del punto final de AppStart, específicamente:

1. La interfaz de consentimiento debe mostrar un título y texto en la primera pantalla. El título y el texto deben provenir de la API y mostrarse completos. No pueden ocultarse, acortarse ni hacerse invisibles.
2. La interfaz de consentimiento debe mostrar los botones indicados por la API y el texto de etiqueta proporcionado por esta. Los botones deben ser visibles de inmediato y no deben estar ocultos.
3. La interfaz de consentimiento debe mostrar los enlaces indicados por la API. El cliente debe poder acceder a los enlaces, pero no es necesario que sean visibles inmediatamente. En cualquier caso, recomendamos que todos los enlaces sean visibles.
4. La interfaz de consentimiento deberá usar los colores indicados por la API. Si esto no es posible debido a restricciones del dispositivo, la interfaz de consentimiento deberá diseñarse de forma que todos los botones tengan la misma importancia.

Punto final de retroalimentación

La respuesta del punto final de AppStart contendrá dos URL: «feedback.accept» y «feedback.reject». La aplicación llamará a estas URL una vez que el usuario acepte o rechace la configuración de privacidad.

Llamar al punto final de retroalimentación

Las URL de los puntos finales de retroalimentación ya están preconstruidas por la llamada a la API de AppStart y no es necesario modificarlas ni añadirlas. Por favor, utilice la URL correcta que corresponda a la elección del usuario.

Respuesta del punto final de retroalimentación

La respuesta de la API será un objeto codificado JSON en 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

Si el usuario hace clic en Ajustes, la aplicación mostrará una segunda pantalla de consentimiento con un código QR (y una URL opcional). El usuario escaneará el código QR y continuará configurando sus opciones de privacidad en su teléfono móvil. Mientras lo hace, la aplicación comprobará el estado del proceso.

Para ello, la respuesta del punto final de AppStart contendrá una URL mediante "customsettings.statusurl". La aplicación 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.

Llamar al punto final de retroalimentación

La URL del punto final del código QR ya está preconstruida por la llamada a la API de punto final de AppStart y no es necesario modificarla ni añadirla. Llámela cada 3 segundos mientras el usuario selecciona sus opciones.

Respuesta del punto final del código QR

La respuesta de la API será un objeto codificado JSON en 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 de implementación

Almacenamiento del consentimiento

Cada vez que el usuario realiza una selección o finaliza el proceso del código QR, la API devolverá el objeto de retroalimentación con todos los detalles. Recomendamos a los desarrolladores de aplicaciones que guarden el objeto completo.

Manejo de errores

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

• errores de la API
  Si una API devuelve un código de estado HTTP inesperado (p. ej., 4xx, 5xx o 6xx), la aplicación lo considerará un error. La aplicación deberá volver a un estado o lógica predeterminados y omitir los siguientes pasos del proceso. Si se envía el código de estado HTTP 3xx o se indica un cambio de ubicación, la aplicación seguirá la URL indicada (Nota: Aplique una regla de seguimiento máximo para evitar bucles infinitos).
  
  
• Tiempos de espera
  Todas las llamadas a la API deben tener un tiempo de espera máximo, por ejemplo, 15 segundos. Si la API no responde dentro de este tiempo, se considerará fuera de línea. La aplicación debe volver a un estado o lógica predeterminados y omitir los siguientes pasos del proceso.
  
  
• Validación SSL
  Especialmente en dispositivos antiguos, la validación SSL puede causar problemas cuando las versiones de certificado o los métodos de cifrado ya no son compatibles. En ese caso, los desarrolladores de aplicaciones pueden llamar a los puntos finales de la API mediante 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 funcionó correctamente. Además, la aplicación debe:
  • Trate todas las propiedades de todos los objetos como opcionales y verifique 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).
  • Sea flexible con la estructura de los objetos. Algunos objetos tienen una estructura dinámica y pueden tener más o menos propiedades. Si una aplicación desconoce una propiedad, la ignorará.
    
    
• Error de estado del código QR
  En los casos en que el punto final de estado del código QR devuelva estado=error, la aplicación debe cancelar la recopilación de consentimiento y reanudarse normalmente.
  
  
• Código QR abandonado

Si se muestra el código QR pero no se observa 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 mediante la URL del punto final de AppStart. En caso de un cambio en la API, actualizaremos la URL del punto final de AppStart a una nueva versión para permitir tener varias versiones activas simultáneamente.