Come integrare l'SDK della CMP di UniConsent per Flutter nelle app mobili

La CMP di UniConsent è un pacchetto per la gestione del consenso GDPR IAB TCF 2.4 nelle app Flutter. Nella directory "uniconsent_demo" trovi un'app demo con la CMP di UniConsent integrata.

Prerequisiti

• Piano CMP di UniConsent con supporto per le app mobili
• Pacchetto SDK della CMP di UniConsent (da richiedere al supporto)

Per iniziare

Per includere il pacchetto UniConsent nel tuo progetto Flutter, aggiungilo come dipendenza nel file pubspec.yaml:

dependencies:
  uniconsent:
    path: ../uniconsent

Quindi, sincronizza la dipendenza eseguendo il seguente comando:

flutter pub get

Personalizzare l'interfaccia del consenso

Prima di integrare l'SDK, personalizza l'aspetto del banner di consenso nella dashboard di UniConsent in modo che corrisponda al tuo brand e ottimizzi i tassi di consenso.

Passaggio 1: stile del brand nella dashboard

Vai a Projects → Select your Project → Settings → Step 5: UI & Style Settings per configurare:

• Main Button Colour: imposta il colore del pulsante di azione principale in linea con il tuo brand
• Main Button Text Colour: regola il colore del testo del pulsante principale per garantirne la leggibilità
• Background Colour: imposta il colore di sfondo del banner in armonia con la tua app
• Text Colour: assicurati che il testo abbia un contrasto adeguato

Passaggio 2: stile avanzato con CSS personalizzato (facoltativo)

Per un controllo più preciso, aggiungi CSS personalizzato nel campo CSS Content dello Step 5. È consigliato per rendere il banner parte integrante della tua app e ottenere il miglior tasso di consenso:

/* 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;
}

Suggerimento: un'interfaccia del consenso ben personalizzata, che risulti nativa nella tua app, ottiene in genere tassi di consenso più elevati. Gli utenti sono più propensi a interagire positivamente con un banner che corrisponde all'aspetto che si aspettano.

Utilizzo

Per usare la CMP di UniConsent nella tua app, segui questi passaggi:

Inizializza la CMP con un App ID fornito dal tuo account manager:

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

Mostra l'interfaccia della 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,
);

Dimensione personalizzata (facoltativa)

Disponibile a partire dalla versione 26.8.0 dell'SDK.

Entrambi i rapporti sono facoltativi: ogni modalità di visualizzazione funziona anche senza. Passa un rapporto (una frazione dello spazio disponibile, maggiore di 0 e al massimo 1) solo per sovrascrivere la dimensione predefinita; i valori non validi generano un ArgumentError:

I rapporti che non si applicano alla modalità di visualizzazione scelta vengono ignorati (page li ignora entrambi).

Gestore degli eventi

Ascolta gli eventi del ciclo di vita dell'SDK con subscribe(). È il modo consigliato per sapere quando l'interfaccia viene mostrata e quando viene chiusa.

Eventi disponibili (CMPEventType):

• CMPEventType.uiDisplay: l'interfaccia del consenso viene mostrata
• CMPEventType.uiClose: l'interfaccia del consenso viene chiusa

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

Ascolta le modifiche del consenso con una callback facoltativa:

// 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}');
});

Per il pieno controllo, usa buildCMPWidget() per incorporare la CMP nel tuo layout:

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

Verifica automaticamente se è necessario richiedere il consenso all'avvio dell'app:

// 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);
}

Ottieni la tcString, se necessario:

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

Leggi lo stato del consenso:

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

Reimposta lo stato del consenso, se necessario:

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

Primo livello personalizzato (Accetta tutto / Rifiuta tutto)

Disponibile a partire dalla versione 26.7.0 dell'SDK. Se crei una tua interfaccia del consenso di primo livello invece di mostrare la webview della CMP, puoi salvare il consenso direttamente:

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

Entrambe le API salvano gli stessi valori di consenso del flusso dell'interfaccia della CMP (chiavi IAB TCF, consenso aggiuntivo e segnali di Consent Mode) e inviano lo stesso evento di chiusura agli iscritti.

Nota: queste API recuperano l'elenco dei fornitori e la configurazione del progetto tramite la rete e restituiscono false se non è stato possibile salvare il consenso (ad es. offline).

Importante: il tuo primo livello personalizzato deve comunque soddisfare i requisiti IAB TCF (indicare finalità e fornitori, e offrire accettazione e rifiuto con uguale evidenza). Gli utenti devono comunque poter aprire l'interfaccia completa della CMP (launchCMP()) per effettuare scelte granulari.

Sincronizzare il consenso con la WebView

Se la tua app apre una WebView che carica una pagina web con il tag della CMP di UniConsent, puoi passare lo stato del consenso nativo in modo che il tag della CMP riconosca il consenso esistente e non mostri di nuovo il banner.

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

Tipi esportati

I seguenti tipi sono disponibili importando package:uniconsent/uniconsent.dart:

• UniConsent: singleton principale dell'SDK
• UniConsentInfo: dati di base del consenso (sdkId, tcString, gdprApplies, vendorListVersion, ecc.)
• ConsentInfo: estende UniConsentInfo con gli elenchi dei consensi a livello di finalità
• DataUsagePurpose: enum degli ID delle finalità IAB TCF 2.4
• KVDBKeys: costanti delle chiavi di archiviazione IAB TCF (ad es. KVDBKeys.tcString, KVDBKeys.purposeConsents)
• CMPDisplayMode: enum per lo stile di visualizzazione (page, modalSheet, dialog)
• CMPEventType: enum per gli eventi del ciclo di vita (sdkInit, ready, uiDisplay, uiClose)
• CMPEvent: oggetto evento con una proprietà type
• CMPEventCallback: typedef per la callback di subscribe()
• LogLevel: debug / prod
• ConsentCallback: typedef per la callback onConsentChanged
• UniConsentCMPContent: il widget principale della CMP per layout personalizzati

Note

1. Gli utenti devono poter accedere a un pulsante o a un link "Impostazioni privacy" nella sezione delle impostazioni della tua applicazione per aprire l'interfaccia della CMP.
2. Puoi usare la funzione shouldRequestConsent() per verificare, in base allo stato, se devi richiedere un nuovo consenso. Mostra l'interfaccia della CMP secondo necessità quando un utente apre l'applicazione.

Registro delle modifiche

26.9.0

• Supporto per IAB TCF 2.4