Leading Consent Management Platform

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

Theme

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:

Parametro	Si applica a	Valore predefinito se omesso
`heightRatio`	`modalSheet`, `dialog`	Sheet: 90% dell'altezza. Dialog: 70%
`widthRatio`	solo `dialog`	90% della larghezza, fino a 500 pixel logici

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.

Per gli utenti di Stati Uniti e Canada, entrambe le API salvano anche la scelta CCPA, US State Privacy e IAB TCF Canada che si applica a loro, con le stesse regole dell'interfaccia della CMP, e scrivono le chiavi IAB GPP e US Privacy. Attiva le modalità API-Only nelle impostazioni del progetto nella dashboard di UniConsent, così il banner della CMP non viene mostrato in quelle regioni.

Salvano anche la scelta delle categorie di cookie dove si applica un banner di categorie di cookie (tutte le categorie, oppure solo Strettamente necessari), e le finalità e i fornitori personalizzati del progetto.

Per sapere quale primo livello mostrare, chiama getPolicy() (dalla versione 26.10.0 dell'SDK). Restituisce la policy che si applica all'utente, con le stesse regole della CMP: gdpr (IAB TCF), tcfca (IAB TCF Canada), uss (US State Privacy), ccpa, categories (vedi Categorie di cookie più avanti) o none.

final cmp = UniConsent.instance;
if (await cmp.shouldRequestConsent()) {
  // l'utente deve fare una scelta: mostra il tuo primo livello per questa policy
  final policy = await cmp.getPolicy(); // gdpr, tcfca o categories
}

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

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 (l'SDK emette uiDisplay e 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

Aprire una schermata specifica e altre opzioni

Apri la CMP su una schermata specifica, ad esempio da un link "Impostazioni privacy" della tua app. La schermata richiesta si apre sempre. Per gli utenti negli Stati Uniti, le schermate delle impostazioni aprono le impostazioni CCPA o US State Privacy che si applicano a loro. Gli utenti in Canada vedono la versione IAB TCF Canada delle schermate IAB TCF.

Schermata	Mostra
`CMPStage.gdprFirstScreen`	Primo livello (banner)
`CMPStage.gdprSecondScreen`	Impostazioni (finalità)
`CMPStage.gdprVendorsScreen`	Fornitori
`CMPStage.ccpaFirstScreen`	Primo livello CCPA
`CMPStage.ccpaSecondScreen`	Impostazioni CCPA
`CMPStage.usStateFirstScreen`	Primo livello US State Privacy
`CMPStage.usStateSecondScreen`	Impostazioni US State Privacy
`CMPStage.categoriesFirstScreen`	Primo livello delle categorie di cookie (banner)
`CMPStage.categoriesSecondScreen`	Impostazioni delle categorie di cookie

final cmp = UniConsent.instance;

// aprire la schermata delle impostazioni
cmp.launchCMP(context, stage: CMPStage.gdprSecondScreen);

// aprire la CMP solo quando serve il consenso (UE e IAB TCF Canada); restituisce se è stata aperta
final opened = await cmp.launchCMPIfNeeded(context);

// log di debug; usa LogLevel.prod nelle build di produzione
cmp.setLogLevel(LogLevel.debug);

// solo per i test: mostrare la CMP come per un utente di un'altra regione, "EU", "CA" (Canada), "CAQC" (Québec), "US" più un codice di stato come "USCA" o "USTX", "BR", "CN", "ZA", "VN" o qualsiasi altro codice paese, oppure "N" (fuori da queste regioni). Si applica anche a getPolicy() e a shouldRequestConsent(); da rimuovere nelle build di produzione
cmp.setTestRegion("CA");

// codice paese dell'utente ("AA" se sconosciuto) e, per Stati Uniti e Canada, il codice dello stato o della provincia
final geo = await cmp.getGEO();
final state = await cmp.getGEOState();

IAB GPP e US Privacy

La CMP salva le chiavi IAB GPP e la chiave US Privacy in lo storage nativo dell'app (SharedPreferences su Android, UserDefaults su iOS), come definite dalle specifiche IAB. Gli SDK pubblicitari della tua app le leggono da lì; non servono modifiche al codice. Le chiavi GPP vengono scritte quando GPP, US State Privacy o IAB TCF Canada è attivato nelle impostazioni del progetto nella dashboard di UniConsent. La chiave US Privacy viene scritta ogni volta che il CCPA è attivato.

Chiave	Valore
`IABGPP_HDR_Version`	Versione GPP (`1`)
`IABGPP_HDR_Sections`	ID delle sezioni nella stringa GPP, separati da `_`
`IABGPP_HDR_GppString`	La stringa GPP completa
`IABGPP_GppSID`	ID delle sezioni che si applicano all'utente, separati da `_`, oppure `-1` se non se ne applica nessuna
`IABGPP_2_String`	Stringa IAB TCF EU, quando si applica il GDPR
`IABGPP_5_String`	Stringa IAB TCF Canada, quando si applica il TCF Canada
`IABGPP_6_String`	Stringa US Privacy, quando si applica il CCPA
`IABGPP_7_String`	Stringa US National (usnat), quando si applica US State Privacy o il CCPA
`IABGPP_8_String` a `IABGPP_27_String`	La sezione dello stato dell'utente (8 California a 27 Rhode Island), quando si applica US State Privacy, o la California con il CCPA, secondo l'impostazione GPP Sections
`IABUSPrivacy_String`	Stringa US Privacy ogni volta che il CCPA è attivato: la scelta dell'utente nella regione CCPA, altrimenti `1---`

Le chiavi vengono aggiornate a ogni caricamento della CMP e dopo ogni scelta di consenso. Quando GPP viene disattivato, le chiavi IABGPP_ vengono rimosse.

Stati Uniti e Canada

Le app supportano le stesse opzioni per Stati Uniti e Canada dei siti web: CCPA, US State Privacy (con l'elenco degli stati e le impostazioni GPP Sections e MSPA) e IAB TCF Canada. shouldRequestConsent() restituisce true per gli utenti del Canada a cui si applica IAB TCF Canada finché non fanno una scelta. La privacy negli Stati Uniti è di tipo opt-out, quindi agli utenti statunitensi non viene chiesto da sé: vedono il banner o le impostazioni USA quando la tua app apre la CMP, ad esempio da un link alle impostazioni privacy. Fino ad allora, quando il CCPA o US State Privacy è attivato, l'SDK scrive le chiavi US Privacy e GPP predefinite per gli utenti statunitensi senza mostrare nulla: nessuna opposizione, oppure opposizione quando il tracciamento pubblicitario è disattivato sul dispositivo. US State Privacy parte disattivato nei nuovi progetti Mobile App; attivalo nella dashboard.

Opposizione al tracciamento pubblicitario sul dispositivo

Quando l'utente ha disattivato il tracciamento pubblicitario sul dispositivo, la CMP lo considera un'opposizione statunitense alla vendita, alla condivisione e alla pubblicità mirata, come fa Global Privacy Control sui siti web. Su iOS è il tracciamento non consentito in App Tracking Transparency; su Android un ID pubblicità eliminato o la limitazione del tracciamento pubblicitario, letti tramite i servizi Google Play quando la tua app li include. Una scelta che l'utente salva poi nel banner ha la precedenza.

Leggere le stringhe GPP e US Privacy

L'SDK restituisce anche le stringhe salvate:

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

Disponibile dalla versione 26.10.0 dell'SDK. Dove una regione usa le categorie di cookie invece di IAB TCF o delle policy USA, la CMP mostra un banner con quattro categorie: Strettamente necessari, Prestazioni, Funzionalità, e Targeting o pubblicità. Si applica a:

LGPD in Brasile, PIPL in Cina, POPIA in Sudafrica e PDPD in Vietnam, quando attivate nelle impostazioni del progetto nella dashboard di UniConsent
le tue regole per gli altri paesi: una regola per un paese e una regola per tutti i paesi rimanenti
un progetto Consent Categories, nelle sue regioni

Le categorie opt-in partono con solo Strettamente necessari attiva, e shouldRequestConsent() restituisce true finché l'utente non fa una scelta, e di nuovo dopo che modifichi la versione della configurazione. Le categorie opt-out partono con tutte le categorie attive (Targeting disattivato quando il tracciamento pubblicitario è disattivato sul dispositivo negli Stati Uniti), e l'app non chiede da sé: gli utenti le modificano dal tuo link alle impostazioni privacy. L'opt-out si applica a una regola opt-out per gli altri paesi e, nelle app, a un progetto Consent Categories negli Stati Uniti.

Apri le schermate delle categorie con CMPStage.categoriesFirstScreen (banner) e CMPStage.categoriesSecondScreen (impostazioni). setTestRegion() accetta anche BR, CN, ZA, VN e altri codici paese, per provare queste regioni.

Finalità personalizzate e fornitori personalizzati

Disponibile dalla versione 26.10.0 dell'SDK. Le finalità personalizzate e i fornitori personalizzati che aggiungi nelle impostazioni del progetto nella dashboard di UniConsent compaiono nelle schermate della CMP: le finalità personalizzate nel primo livello e nelle impostazioni IAB TCF e nelle impostazioni delle categorie di cookie, i fornitori personalizzati nell'elenco dei fornitori IAB TCF. Nelle impostazioni CCPA e US State Privacy sono elencate solo le finalità personalizzate sensibili. Nelle impostazioni delle categorie di cookie i fornitori personalizzati seguono la categoria Targeting o pubblicità. Dove IAB TCF non si applica (categorie di cookie e Stati Uniti), i fornitori personalizzati sono elencati in sola lettura nell'elenco dei fornitori del menu, e nelle impostazioni delle categorie di cookie sotto Targeting o pubblicità.

Per avviare o fermare i tuoi SDK in base a essi, chiedi all'SDK se l'app può usare ora una finalità personalizzata o un fornitore personalizzato. La risposta segue la policy dell'utente, con le stesse regole che la CMP usa per i tag:

IAB TCF, IAB TCF Canada e categorie di cookie opt-in: consentiti solo dopo che l'utente accetta
gli Stati Uniti e le categorie di cookie opt-out: consentiti finché l'utente non si oppone; le finalità personalizzate sensibili richiedono il consenso dell'utente, e i fornitori personalizzati sono disattivati quando il tracciamento pubblicitario è disattivato sul dispositivo negli Stati Uniti
nessuna policy: consentiti

final cmp = UniConsent.instance;
if (await cmp.isCustomPurposeConsented(1)) {
  // avvia l'SDK coperto dalla tua finalità personalizzata 1
}
final vendorAllowed = await cmp.isCustomVendorConsented(2);
final all = await cmp.getCustomConsents(); // {'purposes': {'1': true}, 'vendors': {'2': false}}

Richiamale dopo la chiusura della CMP o una modifica del consenso. Gli ID che il progetto non ha, e tutti gli ID prima che l'SDK sia pronto, restituiscono false.

Divulgazione degli SDK di terze parti

La CMP può elencare gli SDK di terze parti della tua app (reti pubblicitarie, analisi, attribuzione e altri) con la loro azienda, il loro utilizzo e la loro informativa sulla privacy. Gli utenti li vedono nell'elenco dei fornitori, in sola lettura in tutte le regioni: non ci sono interruttori e la tua app continua ad attivare o disattivare ogni SDK in base alle scelte dell'utente per le finalità o le categorie di cookie.

Per impostare l'elenco, attiva Enable Third-party SDKs in Step 4: Advanced Features del tuo progetto app, scegli i tuoi SDK nella scheda Third-party SDKs o aggiungine di tuoi, poi salva e pubblica. Non serve codice nella tua app.

Note

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.
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.10.0

Chiavi IAB GPP e US Privacy per gli SDK pubblicitari
US State Privacy e IAB TCF Canada nelle app, anche con primo livello personalizzato
Nuovi getGPPString(), getGPPSID() e getUSPrivacyString()
Apertura di una schermata specifica con launchCMP(context, stage:); nuovi launchCMPIfNeeded(), getGEO() e getGEOState()
Apertura del primo livello CCPA e US State Privacy con CMPStage.ccpaFirstScreen e CMPStage.usStateFirstScreen; nuovo setTestRegion() per provare la CMP come un utente di un'altra regione, ad esempio il Canada
Categorie di cookie nelle app: LGPD (Brasile), PIPL (Cina), POPIA (Sudafrica), PDPD (Vietnam), le tue regole per gli altri paesi e i progetti Consent Categories, con CMPStage.categoriesFirstScreen e CMPStage.categoriesSecondScreen
Nuovo getPolicy(); agreeAll() e rejectAll() salvano anche le categorie di cookie, le finalità personalizzate e i fornitori personalizzati
setTestRegion() accetta anche BR, CN, ZA, VN e altri codici paese, e si applica a getPolicy() e a shouldRequestConsent()
Nuovi isCustomPurposeConsented(), isCustomVendorConsented() e getCustomConsents(): le finalità e i fornitori personalizzati che l'app può usare ora secondo la policy dell'utente

26.9.0

Supporto per IAB TCF 2.4

Gestione del consenso per il web

CMP per app mobili

Google Consent Mode

Google Tag Gateway

CMP certificata IAB TCF

Consenso Microsoft UET

Amazon Consent Signal

Consenso Meta Pixel

Consenso TikTok Pixel

Scanner dei cookie

Per gli editori

Per gli inserzionisti

Per Shopify

Per WordPress

Confronta le CMP