Leading Consent Management Platform

Compliant with GDPR, CCPA, COPPA, LGPD, PECR, PDPA, PIPEDA, and more.

Theme

Cómo integrar el SDK de UniConsent CMP para Flutter con aplicaciones móviles

UniConsent CMP es un paquete para gestionar el consentimiento GDPR IAB TCF 2.4 en aplicaciones Flutter. Puede encontrar una aplicación de demostración integrada con UniConsent CMP en el directorio "uniconsent_demo".

Requisitos previos

Plan de UniConsent CMP con soporte para aplicaciones móviles
Paquete del SDK de UniConsent CMP (solicitar al soporte)

Primeros pasos

Para incluir el paquete de UniConsent en su proyecto Flutter, agréguelo como dependencia en su archivo pubspec.yaml:

dependencies:
  uniconsent:
    path: ../uniconsent

Luego, sincronice la dependencia ejecutando el siguiente comando:

flutter pub get

Personalizar la interfaz de consentimiento

Antes de integrar el SDK, personalice la apariencia del banner de consentimiento en el Panel de UniConsent para que coincida con su marca y optimice las tasas de consentimiento.

Paso 1: Estilo de marca en el panel

Vaya a Projects → Seleccione su Proyecto → Settings → Step 5: UI & Style Settings para configurar:

Main Button Colour — Establezca el color del botón de acción principal para que coincida con su marca
Main Button Text Colour — Ajuste el color del texto del botón principal para mejorar la legibilidad
Background Colour — Establezca el color de fondo del banner para que se integre con su aplicación
Text Colour — Asegúrese de que el texto del cuerpo tenga el contraste adecuado

Paso 2: Estilo avanzado con CSS personalizado (Opcional)

Para un control más preciso, agregue CSS personalizado en el campo CSS Content en el Paso 5. Esto se recomienda para que el banner se sienta nativo en su aplicación y logre la mejor tasa de consentimiento:

/* Example: Style the accept button to match your brand */
.unic-btn-accept {
  background-color: #4CAF50;
  border-radius: 8px;
  font-weight: 600;
}

/* Example: Adjust banner font */
.unic-banner {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

/* Example: Make the reject button less prominent */
.unic-btn-reject {
  background-color: transparent;
  border: 1px solid #ccc;
  color: #666;
}

Consejo: Una interfaz de consentimiento bien personalizada que se sienta nativa en su aplicación generalmente logra tasas de consentimiento más altas. Los usuarios tienen más probabilidades de interactuar positivamente con un banner que coincide con la apariencia que esperan.

Uso

Para usar UniConsent CMP en su aplicación, siga estos pasos:

Inicialice el CMP con un App ID proporcionado por su gestor de cuenta:

// Init CMP with appId
UniConsent.instance.setAppId("YOUR_APP_ID_CHANGE_THIS");
// Set language (Optional)
UniConsent.instance.setLanguage("EN");

Mostrar la interfaz del CMP:

// Display CMP as full-screen page (default)
UniConsent.instance.launchCMP(context);

// Display CMP as a modal bottom sheet
UniConsent.instance.launchCMP(context, displayMode: CMPDisplayMode.modalSheet);

// Display CMP as a modal bottom sheet at 70% of the available height
UniConsent.instance.launchCMP(
  context,
  displayMode: CMPDisplayMode.modalSheet,
  heightRatio: 0.7,
);

// Display CMP as a center dialog
UniConsent.instance.launchCMP(context, displayMode: CMPDisplayMode.dialog);

// Display CMP as a center dialog at 85% width and 70% height
UniConsent.instance.launchCMP(
  context,
  displayMode: CMPDisplayMode.dialog,
  widthRatio: 0.85,
  heightRatio: 0.7,
);

Tamaño personalizado (opcional)

Disponible desde la versión 26.8.0 del SDK.

Ambas proporciones son opcionales: todos los modos de visualización funcionan sin ellas. Pase una proporción (una fracción del espacio disponible, mayor que 0 y como máximo 1) solo para sobrescribir el tamaño predeterminado; los valores no válidos lanzan ArgumentError:

Parámetro	Se aplica a	Valor predeterminado si se omite
`heightRatio`	`modalSheet`, `dialog`	Hoja: 90% de la altura. Diálogo: 70%
`widthRatio`	Solo `dialog`	90% del ancho, hasta 500 píxeles lógicos

Las proporciones que no se aplican al modo de visualización elegido se ignoran (page ignora ambas).

Manejador de eventos

Escuche los eventos del ciclo de vida del SDK con subscribe(). Esta es la forma recomendada de saber cuándo se muestra la interfaz y cuándo se cierra.

Eventos disponibles (CMPEventType):

CMPEventType.uiDisplay — La interfaz de consentimiento se muestra
CMPEventType.uiClose — La interfaz de consentimiento se cierra

UniConsent.instance.subscribe((event) {
  switch (event.type) {
    case CMPEventType.uiDisplay:
      print('CMP UI displayed');
      break;
    case CMPEventType.uiClose:
      print('CMP UI closed');
      break;
    default:
      break;
  }
});

Escuche los cambios de consentimiento con un callback opcional:

// Display CMP UI with consent change callback
UniConsent.instance.launchCMP(context, onConsentChanged: (info) {
  // Called when the user saves consent choices
  print('Consent updated: ${info?.tcString}');
});

Para un control completo, use buildCMPWidget() para integrar el CMP en su propio diseño:

// Embed in your own widget tree
UniConsent.instance.buildCMPWidget(
  onConsentChanged: (info) { /* ... */ },
  onClose: () { /* dismiss your custom UI */ },
);

Verificar automáticamente si se necesita consentimiento al iniciar la aplicación:

// Check if consent should be requested (e.g. first visit, or vendor list updated)
final shouldRequest = await UniConsent.instance.shouldRequestConsent();
if (shouldRequest) {
  UniConsent.instance.launchCMP(context);
}

Obtener el tcString si es necesario:

// Get tcString
final info = await UniConsent.instance.getConsentInfo();
print(info?.tcString);

Leer el estado del consentimiento:

// Read consent status
final info = await UniConsent.instance.getConsentInfo();
if (info is ConsentInfo &&
    info.purposeConsents.contains(DataUsagePurpose.useLimitedDataToSelectAds)) {
  // do something
}

Restablecer el estado del consentimiento si es necesario:

// Clear all consent data
await UniConsent.instance.clearAll();

Primera capa personalizada (Aceptar todo / Rechazar todo)

Disponible desde la versión 26.7.0 del SDK. Si crea su propia interfaz de consentimiento de primera capa en lugar de mostrar la webview del CMP, puede guardar el consentimiento directamente:

// Grant consent for all purposes, special features and vendors
final saved = await UniConsent.instance.agreeAll();

// Reject all purposes, special features and vendors
final saved = await UniConsent.instance.rejectAll();

Ambas API guardan los mismos valores de consentimiento que el flujo de la interfaz del CMP (claves IAB TCF, consentimiento adicional y señales de consent mode) y disparan el mismo evento de cierre para los suscriptores.

Para los usuarios de EE. UU. y Canadá, ambas API también guardan la elección de CCPA, US State Privacy e IAB TCF Canadá que les corresponde, con las mismas reglas que la interfaz de la CMP, y escriben las claves IAB GPP y US Privacy. Active los modos API-Only en la configuración del proyecto en el panel de UniConsent para que el banner de la CMP no se muestre en esas regiones.

También guardan la elección de categorías de cookies donde se aplica un banner de categorías de cookies (todas las categorías, o solo Estrictamente necesarias), y las finalidades y los proveedores personalizados del proyecto.

Para saber qué primera capa mostrar, llame a getPolicy() (desde la versión 26.10.0 del SDK). Devuelve la política que se aplica al usuario, con las mismas reglas que la CMP: gdpr (IAB TCF), tcfca (IAB TCF Canadá), uss (US State Privacy), ccpa, categories (vea Categorías de cookies más abajo) o none.

final cmp = UniConsent.instance;
if (await cmp.shouldRequestConsent()) {
  // el usuario debe tomar una decisión: muestre su primera capa para esta política
  final policy = await cmp.getPolicy(); // gdpr, tcfca o categories
}

Nota: Estas API obtienen la lista de proveedores y la configuración del proyecto a través de la red y devuelven false si el consentimiento no pudo guardarse (por ejemplo, sin conexión).

Importante: Su primera capa personalizada debe seguir cumpliendo los requisitos de IAB TCF (divulgar las finalidades y los proveedores, y ofrecer aceptar y rechazar con la misma prominencia). Los usuarios deben poder seguir abriendo la interfaz completa del CMP (launchCMP()) para tomar decisiones granulares.

Sincronizar consentimiento con WebView

Si su aplicación abre un WebView que carga una página web con la etiqueta de UniConsent CMP, puede pasar el estado de consentimiento nativo para que la etiqueta del CMP reconozca el consentimiento existente y no muestre el banner nuevamente.

import 'package:webview_flutter/webview_flutter.dart';
import 'package:uniconsent/uniconsent.dart';

final controller = WebViewController();
controller
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..setNavigationDelegate(NavigationDelegate(
    onPageStarted: (url) async {
      // Inject consent at page start, before CMP tag runs
      await UniConsent.instance.syncConsent(controller);
    },
  ))
  ..loadRequest(Uri.parse('https://example.com'));

Tipos exportados

Los siguientes tipos están disponibles al importar package:uniconsent/uniconsent.dart:

UniConsent — singleton principal del SDK
UniConsentInfo — datos base de consentimiento (sdkId, tcString, gdprApplies, vendorListVersion, etc.)
ConsentInfo — extiende UniConsentInfo con listas de consentimiento a nivel de propósito
DataUsagePurpose — enum de IDs de propósitos IAB TCF 2.4
KVDBKeys — constantes de claves de almacenamiento IAB TCF (por ejemplo, KVDBKeys.tcString, KVDBKeys.purposeConsents)
CMPDisplayMode — enum para el estilo de visualización (page, modalSheet, dialog)
CMPEventType — enum para eventos del ciclo de vida (el SDK emite uiDisplay y uiClose)
CMPEvent — objeto de evento con una propiedad type
CMPEventCallback — typedef para el callback de subscribe()
LogLevel — debug / prod
ConsentCallback — typedef para el callback onConsentChanged
UniConsentCMPContent — el widget principal del CMP para diseños personalizados

Abrir una pantalla concreta y otras opciones

Abra la CMP en una pantalla concreta, por ejemplo desde un enlace "Configuración de privacidad" de su app. La pantalla solicitada siempre se abre. Para los usuarios de EE. UU., las pantallas de configuración abren la configuración de CCPA o US State Privacy que les corresponde. Los usuarios de Canadá ven la versión IAB TCF Canada de las pantallas de IAB TCF.

Pantalla	Muestra
`CMPStage.gdprFirstScreen`	Primera capa (banner)
`CMPStage.gdprSecondScreen`	Configuración (finalidades)
`CMPStage.gdprVendorsScreen`	Proveedores
`CMPStage.ccpaFirstScreen`	Primera capa de CCPA
`CMPStage.ccpaSecondScreen`	Configuración de CCPA
`CMPStage.usStateFirstScreen`	Primera capa de US State Privacy
`CMPStage.usStateSecondScreen`	Configuración de US State Privacy
`CMPStage.categoriesFirstScreen`	Primera capa de categorías de cookies (banner)
`CMPStage.categoriesSecondScreen`	Configuración de categorías de cookies

final cmp = UniConsent.instance;

// abrir la pantalla de configuración
cmp.launchCMP(context, stage: CMPStage.gdprSecondScreen);

// abrir la CMP solo cuando se necesita consentimiento (UE e IAB TCF Canadá); devuelve si se abrió
final opened = await cmp.launchCMPIfNeeded(context);

// registros de depuración; use LogLevel.prod en las versiones de producción
cmp.setLogLevel(LogLevel.debug);

// solo para pruebas: mostrar la CMP como para un usuario de otra región, "EU", "CA" (Canadá), "CAQC" (Quebec), "US" más un código de estado como "USCA" o "USTX", "BR", "CN", "ZA", "VN" o cualquier otro código de país, o "N" (fuera de estas regiones). También se aplica a getPolicy() y shouldRequestConsent(); elimínelo en las versiones de producción
cmp.setTestRegion("CA");

// código de país del usuario ("AA" si se desconoce) y, para EE. UU. y Canadá, el código del estado o la provincia
final geo = await cmp.getGEO();
final state = await cmp.getGEOState();

IAB GPP y US Privacy

La CMP guarda las claves IAB GPP y la clave US Privacy en el almacenamiento nativo de la app (SharedPreferences en Android, UserDefaults en iOS), tal como las definen las especificaciones de IAB. Los SDK de publicidad de su app las leen desde ahí; no hace falta cambiar código. Las claves GPP se escriben cuando GPP, US State Privacy o IAB TCF Canadá está activado en la configuración del proyecto en el panel de UniConsent. La clave US Privacy se escribe siempre que la CCPA esté activada.

Clave	Valor
`IABGPP_HDR_Version`	Versión de GPP (`1`)
`IABGPP_HDR_Sections`	ID de sección en la cadena GPP, separados por `_`
`IABGPP_HDR_GppString`	La cadena GPP completa
`IABGPP_GppSID`	ID de sección que se aplican al usuario, separados por `_`, o `-1` si no se aplica ninguno
`IABGPP_2_String`	Cadena IAB TCF EU, cuando se aplica el RGPD
`IABGPP_5_String`	Cadena IAB TCF Canadá, cuando se aplica TCF Canadá
`IABGPP_6_String`	Cadena US Privacy, cuando se aplica la CCPA
`IABGPP_7_String`	Cadena US National (usnat), cuando se aplica US State Privacy o la CCPA
`IABGPP_8_String` a `IABGPP_27_String`	La sección del estado del usuario (8 California a 27 Rhode Island), cuando se aplica US State Privacy, o California con la CCPA, según el ajuste GPP Sections
`IABUSPrivacy_String`	Cadena US Privacy siempre que la CCPA esté activada: la elección del usuario en la región CCPA; si no, `1---`

Las claves se actualizan cada vez que se carga la CMP y después de cada elección de consentimiento. Al desactivar GPP, se eliminan las claves IABGPP_.

EE. UU. y Canadá

Las apps admiten las mismas opciones para EE. UU. y Canadá que los sitios web: CCPA, US State Privacy (con la lista de estados y los ajustes GPP Sections y MSPA) e IAB TCF Canadá. shouldRequestConsent() devuelve true para los usuarios de Canadá a los que se aplica IAB TCF Canadá hasta que toman una decisión. La privacidad en EE. UU. es de exclusión voluntaria, así que a los usuarios de EE. UU. no se les pregunta por sí solo: ven el banner o los ajustes de EE. UU. cuando su app abre la CMP, por ejemplo desde un enlace a la configuración de privacidad. Hasta entonces, cuando la CCPA o US State Privacy están activadas, el SDK escribe las claves US Privacy y GPP predeterminadas para los usuarios de EE. UU. sin mostrar nada: sin exclusión, o con exclusión cuando el seguimiento publicitario está desactivado en el dispositivo. US State Privacy empieza desactivado en los proyectos Mobile App nuevos; actívelo en el panel.

Exclusión del seguimiento publicitario del dispositivo

Si el usuario ha desactivado el seguimiento publicitario en el dispositivo, la CMP lo trata como una exclusión de EE. UU. de la venta, el intercambio y la publicidad dirigida, como hace Global Privacy Control en los sitios web. En iOS es el seguimiento no permitido en App Tracking Transparency; en Android, un ID de publicidad eliminado o la limitación del seguimiento publicitario, que se lee a través de los servicios de Google Play cuando su app los incluye. Una elección que el usuario guarde después en el banner tiene prioridad.

Leer las cadenas GPP y US Privacy

El SDK también devuelve las cadenas guardadas:

final gppString = await UniConsent.instance.getGPPString();
final gppSid = await UniConsent.instance.getGPPSID();
final usPrivacy = await UniConsent.instance.getUSPrivacyString();

Categorías de cookies

Disponible desde la versión 26.10.0 del SDK. Donde una región usa categorías de cookies en lugar de IAB TCF o las políticas de EE. UU., la CMP muestra un banner con cuatro categorías: Estrictamente necesarias, Rendimiento, Funcionalidad, y Segmentación o publicidad. Se aplica a:

LGPD en Brasil, PIPL en China, POPIA en Sudáfrica y PDPD en Vietnam, cuando están activadas en la configuración del proyecto en el panel de UniConsent
sus reglas para otros países: una regla para un país y una regla para todos los demás países
un proyecto Consent Categories, en sus regiones

Las categorías opt-in empiezan solo con Estrictamente necesarias activada, y shouldRequestConsent() devuelve true hasta que el usuario toma una decisión, y de nuevo después de cambiar la versión de configuración. Las categorías opt-out empiezan con todas las categorías activadas (Segmentación desactivada cuando el seguimiento publicitario está desactivado en el dispositivo en EE. UU.), y la app no pregunta por sí sola: los usuarios las cambian desde su enlace a la configuración de privacidad. Opt-out se aplica a una regla opt-out para otros países y, en apps, a un proyecto Consent Categories en EE. UU.

Abra las pantallas de categorías con CMPStage.categoriesFirstScreen (banner) y CMPStage.categoriesSecondScreen (configuración). setTestRegion() también acepta BR, CN, ZA, VN y otros códigos de país, para probar estas regiones.

Finalidades personalizadas y proveedores personalizados

Disponible desde la versión 26.10.0 del SDK. Las finalidades personalizadas y los proveedores personalizados que añada en la configuración del proyecto en el panel de UniConsent se muestran en las pantallas de la CMP: las finalidades personalizadas en la primera capa y la configuración de IAB TCF y en la configuración de categorías de cookies, los proveedores personalizados en la lista de proveedores de IAB TCF. En la configuración de CCPA y US State Privacy solo se listan las finalidades personalizadas sensibles. En la configuración de categorías de cookies los proveedores personalizados siguen la categoría Segmentación o publicidad. Donde IAB TCF no se aplica (categorías de cookies y EE. UU.), los proveedores personalizados se listan en modo de solo lectura en la lista de proveedores del menú, y en la configuración de categorías de cookies en Segmentación o publicidad.

Para iniciar o detener sus propios SDK según ellos, pregunte al SDK si la app puede usar ahora una finalidad personalizada o un proveedor personalizado. La respuesta sigue la política del usuario, con las mismas reglas que la CMP usa para las etiquetas:

IAB TCF, IAB TCF Canadá y categorías de cookies opt-in: permitidos solo después de que el usuario acepte
EE. UU. y categorías de cookies opt-out: permitidos hasta que el usuario se excluya; las finalidades personalizadas sensibles necesitan la aceptación del usuario, y los proveedores personalizados se desactivan cuando el seguimiento publicitario está desactivado en el dispositivo en EE. UU.
sin política: permitidos

final cmp = UniConsent.instance;
if (await cmp.isCustomPurposeConsented(1)) {
  // inicie el SDK que cubre su finalidad personalizada 1
}
final vendorAllowed = await cmp.isCustomVendorConsented(2);
final all = await cmp.getCustomConsents(); // {'purposes': {'1': true}, 'vendors': {'2': false}}

Vuelva a llamarlas después de que la CMP se cierre o cambie el consentimiento. Los ID que el proyecto no tiene, y todos los ID antes de que el SDK esté listo, devuelven false.

Divulgación de SDK de terceros

La CMP puede listar los SDK de terceros de su app (redes publicitarias, analítica, atribución y otros) con su empresa, su finalidad y su política de privacidad. Los usuarios los ven en la lista de proveedores, de solo lectura en todas las regiones: no hay interruptores, y su app sigue activando o desactivando cada SDK según las elecciones del usuario para los propósitos o las categorías de cookies.

Para definir la lista, active Enable Third-party SDKs en Step 4: Advanced Features de su proyecto de app, elija sus SDK en la pestaña Third-party SDKs o añada los suyos, y luego guarde y publique. No necesita código en su app.

Notas

Los usuarios deben tener la posibilidad de acceder a un botón o enlace de "Configuración de privacidad" en la sección de ajustes de su aplicación para abrir la interfaz del CMP.
Puede utilizar la función shouldRequestConsent() para verificar si debe solicitar un nuevo consentimiento según el estado. Muestre la interfaz del CMP según sea necesario cuando un usuario abra la aplicación.

Registro de cambios

26.10.0

Claves IAB GPP y US Privacy para los SDK de publicidad
US State Privacy e IAB TCF Canadá en apps, también con primera capa personalizada
Nuevos getGPPString(), getGPPSID() y getUSPrivacyString()
Abrir una pantalla concreta con launchCMP(context, stage:); nuevos launchCMPIfNeeded(), getGEO() y getGEOState()
Abrir la primera capa de CCPA y de US State Privacy con CMPStage.ccpaFirstScreen y CMPStage.usStateFirstScreen; nuevo setTestRegion() para probar la CMP como un usuario de otra región, por ejemplo Canadá
Categorías de cookies en apps: LGPD (Brasil), PIPL (China), POPIA (Sudáfrica), PDPD (Vietnam), sus reglas para otros países y los proyectos Consent Categories, con CMPStage.categoriesFirstScreen y CMPStage.categoriesSecondScreen
Nuevo getPolicy(); agreeAll() y rejectAll() también guardan las categorías de cookies, las finalidades personalizadas y los proveedores personalizados
setTestRegion() también acepta BR, CN, ZA, VN y otros códigos de país, y se aplica a getPolicy() y shouldRequestConsent()
Nuevos isCustomPurposeConsented(), isCustomVendorConsented() y getCustomConsents(): las finalidades y los proveedores personalizados que la app puede usar ahora según la política del usuario

26.9.0

Compatibilidad con IAB TCF 2.4

Gestión de Consentimiento para Web

CMP para apps móviles

Google Consent Mode

Google Tag Gateway

CMP certificada IAB TCF

Consentimiento de Microsoft UET

Amazon Consent Signal

Consentimiento del Meta Pixel

Consentimiento del TikTok Pixel

Escáner de Cookies

Para Editores

Para Anunciantes

Para Shopify

Para WordPress

Comparar CMP