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.3 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:

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.

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()
  ..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.3
• 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 (sdkInit, ready, uiDisplay, 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

Notas

1. 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.
2. 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.