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 center dialog
UniConsent.instance.launchCMP(context, displayMode: CMPDisplayMode.dialog);

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();

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.