Compliant with GDPR, CCPA, COPPA, LGPD, PECR, PDPA, PIPEDA, and more.
UniConsent CMP ist ein Paket zur Verwaltung der GDPR IAB TCF 2.4 Einwilligung in Flutter-Apps. Eine Demo-App mit integrierter UniConsent CMP finden Sie im Verzeichnis "uniconsent_demo".
Um das UniConsent-Paket in Ihr Flutter-Projekt einzubinden, fügen Sie es als Abhängigkeit in Ihrer pubspec.yaml-Datei hinzu:
dependencies:
uniconsent:
path: ../uniconsent
Synchronisieren Sie dann die Abhängigkeit mit folgendem Befehl:
flutter pub get
Bevor Sie das SDK integrieren, passen Sie das Erscheinungsbild des Einwilligungsbanners im UniConsent Dashboard an, um es an Ihre Marke anzupassen und die Einwilligungsrate zu optimieren.
Gehen Sie zu Projects → Projekt auswählen → Settings → Step 5: UI & Style Settings, um folgende Einstellungen vorzunehmen:
Für eine präzisere Steuerung fügen Sie benutzerdefiniertes CSS im Feld CSS Content unter Schritt 5 hinzu. Dies wird empfohlen, damit sich das Banner nativ in Ihre App einfügt und die beste Einwilligungsrate erzielt wird:
/* 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;
}
Tipp: Eine gut gebrandete Einwilligungs-UI, die sich nativ in Ihre App einfügt, erzielt typischerweise höhere Einwilligungsraten. Nutzer interagieren eher positiv mit einem Banner, das dem erwarteten Erscheinungsbild entspricht.
Um UniConsent CMP in Ihrer App zu nutzen, folgen Sie diesen Schritten:
Initialisieren Sie die CMP mit einer App-ID von Ihrem Account Manager:
// Init CMP with appId
UniConsent.instance.setAppId("YOUR_APP_ID_CHANGE_THIS");
// Set language (Optional)
UniConsent.instance.setLanguage("EN");
CMP-UI anzeigen:
// 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,
);
Verfügbar ab SDK-Version 26.8.0.
Beide Ratios sind optional — jeder Anzeigemodus funktioniert auch ohne sie. Übergeben Sie ein Ratio (ein Bruchteil des verfügbaren Platzes, größer als 0 und höchstens 1) nur, um die Standardgröße zu überschreiben; ungültige Werte werfen einen ArgumentError:
| Parameter | Gilt für | Standard, wenn nicht angegeben |
|---|---|---|
heightRatio | modalSheet, dialog | Sheet: 90 % der Höhe. Dialog: 70 % |
widthRatio | nur dialog | 90 % der Breite, maximal 500 logische Pixel |
Ratios, die für den gewählten Anzeigemodus nicht relevant sind, werden ignoriert (page ignoriert beide).
Verwenden Sie subscribe(), um auf SDK-Lebenszyklusereignisse zu lauschen. Dies ist die empfohlene Methode, um zu wissen, wann die UI angezeigt und wann sie geschlossen wird.
Verfügbare Ereignisse (CMPEventType):
CMPEventType.uiDisplay — Einwilligungs-UI wird angezeigtCMPEventType.uiClose — Einwilligungs-UI wird geschlossenUniConsent.instance.subscribe((event) {
switch (event.type) {
case CMPEventType.uiDisplay:
print('CMP UI displayed');
break;
case CMPEventType.uiClose:
print('CMP UI closed');
break;
default:
break;
}
});
Auf Einwilligungsänderungen mit einem optionalen Callback lauschen:
// 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}');
});
Für volle Kontrolle verwenden Sie buildCMPWidget(), um die CMP in Ihr eigenes Layout einzubetten:
// Embed in your own widget tree
UniConsent.instance.buildCMPWidget(
onConsentChanged: (info) { /* ... */ },
onClose: () { /* dismiss your custom UI */ },
);
Automatisch prüfen, ob eine Einwilligung beim App-Start erforderlich ist:
// 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);
}
Den tcString abrufen, falls erforderlich:
// Get tcString
final info = await UniConsent.instance.getConsentInfo();
print(info?.tcString);
Den Einwilligungsstatus auslesen:
// Read consent status
final info = await UniConsent.instance.getConsentInfo();
if (info is ConsentInfo &&
info.purposeConsents.contains(DataUsagePurpose.useLimitedDataToSelectAds)) {
// do something
}
Einwilligungsstatus zurücksetzen, falls erforderlich:
// Clear all consent data
await UniConsent.instance.clearAll();
Verfügbar ab SDK-Version 26.7.0. Wenn Sie Ihre eigene First-Layer-Einwilligungsoberfläche erstellen, anstatt die CMP-Webview anzuzeigen, können Sie die Einwilligung direkt speichern:
// 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();
Beide APIs speichern dieselben Einwilligungswerte wie der CMP-UI-Flow (IAB-TCF-Schlüssel, Additional Consent und Consent-Mode-Signale) und lösen dasselbe Close-Event für Abonnenten aus.
Für Nutzer in den USA und Kanada speichern beide APIs zusätzlich die jeweils geltende Entscheidung für CCPA, US State Privacy und IAB TCF Kanada, nach denselben Regeln wie die CMP Oberfläche, und schreiben die IAB GPP und US Privacy Schlüssel. Aktivieren Sie die API-Only Modi in den Projekteinstellungen des UniConsent Dashboards, damit das CMP Banner für diese Regionen nicht angezeigt wird.
Außerdem speichern sie die Entscheidung zu den Cookie-Kategorien, wo ein Cookie-Kategorien-Banner gilt (alle Kategorien oder nur „Unbedingt erforderlich“), sowie die benutzerdefinierten Zwecke und benutzerdefinierten Anbieter des Projekts.
Um zu wissen, welchen First Layer Sie anzeigen sollen, rufen Sie getPolicy() auf (ab SDK Version 26.10.0). Es gibt die für den Nutzer geltende Richtlinie zurück, nach denselben Regeln wie die CMP: gdpr (IAB TCF), tcfca (IAB TCF Kanada), uss (US State Privacy), ccpa, categories (siehe Cookie-Kategorien unten) oder none.
final cmp = UniConsent.instance;
if (await cmp.shouldRequestConsent()) {
// der Nutzer muss eine Entscheidung treffen: Ihren First Layer für diese Richtlinie anzeigen
final policy = await cmp.getPolicy(); // gdpr, tcfca oder categories
}
Hinweis: Diese APIs laden die Vendor-Liste und die Projektkonfiguration über das Netzwerk und geben
falsezurück, wenn die Einwilligung nicht gespeichert werden konnte (z. B. offline).Wichtig: Ihr benutzerdefinierter First Layer muss weiterhin die IAB-TCF-Anforderungen erfüllen (Zwecke und Anbieter offenlegen sowie Akzeptieren und Ablehnen gleichwertig anbieten). Nutzer sollten weiterhin die vollständige CMP-Oberfläche (
launchCMP()) öffnen können, um granulare Entscheidungen zu treffen.
Wenn Ihre App eine WebView öffnet, die eine Webseite mit dem UniConsent CMP-Tag lädt, können Sie den nativen Einwilligungsstatus übergeben, damit das CMP-Tag die bestehende Einwilligung erkennt und das Banner nicht erneut anzeigt.
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'));
Die folgenden Typen sind beim Import von package:uniconsent/uniconsent.dart verfügbar:
UniConsent — Haupt-SDK-SingletonUniConsentInfo — Basis-Einwilligungsdaten (sdkId, tcString, gdprApplies, vendorListVersion, etc.)ConsentInfo — erweitert UniConsentInfo mit Einwilligungslisten auf ZweckebeneDataUsagePurpose — Enum der IAB TCF 2.4 Zweck-IDsKVDBKeys — IAB TCF Speicherschlüssel-Konstanten (z. B. KVDBKeys.tcString, KVDBKeys.purposeConsents)CMPDisplayMode — Enum für den Anzeigestil (page, modalSheet, dialog)CMPEventType — Enum für Lebenszyklusereignisse (das SDK sendet uiDisplay und uiClose)CMPEvent — Ereignisobjekt mit einer type-EigenschaftCMPEventCallback — Typedef für den subscribe()-CallbackLogLevel — debug / prodConsentCallback — Typedef für den onConsentChanged-CallbackUniConsentCMPContent — das Kern-CMP-Widget für benutzerdefinierte LayoutsÖffnen Sie die CMP auf einem bestimmten Bildschirm, zum Beispiel über einen Link „Datenschutzeinstellungen“ in Ihrer App. Der angeforderte Bildschirm wird immer geöffnet. Für Nutzer in den USA öffnen die Einstellungsbildschirme die für sie geltenden CCPA- oder US-State-Privacy-Einstellungen. Nutzer in Kanada sehen die IAB-TCF-Canada-Version der IAB-TCF-Bildschirme.
| Bildschirm | Zeigt |
|---|---|
CMPStage.gdprFirstScreen | Erste Ebene (Banner) |
CMPStage.gdprSecondScreen | Einstellungen (Zwecke) |
CMPStage.gdprVendorsScreen | Anbieter |
CMPStage.ccpaFirstScreen | Erste Ebene CCPA |
CMPStage.ccpaSecondScreen | CCPA-Einstellungen |
CMPStage.usStateFirstScreen | Erste Ebene US State Privacy |
CMPStage.usStateSecondScreen | US-State-Privacy-Einstellungen |
CMPStage.categoriesFirstScreen | Erste Ebene der Cookie-Kategorien (Banner) |
CMPStage.categoriesSecondScreen | Einstellungen der Cookie-Kategorien |
final cmp = UniConsent.instance;
// Einstellungsbildschirm öffnen
cmp.launchCMP(context, stage: CMPStage.gdprSecondScreen);
// CMP nur öffnen, wenn eine Einwilligung nötig ist (EU und IAB TCF Kanada), gibt zurück, ob sie geöffnet wurde
final opened = await cmp.launchCMPIfNeeded(context);
// Debug-Logs, in Release-Builds LogLevel.prod verwenden
cmp.setLogLevel(LogLevel.debug);
// nur zum Testen: CMP wie für einen Nutzer in einer anderen Region anzeigen, "EU", "CA" (Kanada), "CAQC" (Quebec), "US" plus Bundesstaatscode wie "USCA" oder "USTX", "BR", "CN", "ZA", "VN" oder ein anderer Ländercode, oder "N" (außerhalb dieser Regionen). Gilt auch für getPolicy() und shouldRequestConsent(); in Release-Builds entfernen
cmp.setTestRegion("CA");
// Ländercode des Nutzers ("AA", wenn unbekannt) und für die USA und Kanada der Code des Bundesstaats bzw. der Provinz
final geo = await cmp.getGEO();
final state = await cmp.getGEOState();
Die CMP speichert die IAB GPP Schlüssel und den US Privacy Schlüssel in den nativen Speicher der App (SharedPreferences unter Android, UserDefaults unter iOS), wie in den IAB Spezifikationen definiert. Werbe-SDKs in Ihrer App lesen sie dort aus; Codeänderungen sind nicht nötig. Die GPP Schlüssel werden geschrieben, wenn GPP, US State Privacy oder IAB TCF Kanada in den Projekteinstellungen des UniConsent Dashboards aktiviert ist. Der US Privacy Schlüssel wird geschrieben, sobald CCPA aktiviert ist.
| Schlüssel | Wert |
|---|---|
IABGPP_HDR_Version | GPP Version (1) |
IABGPP_HDR_Sections | Abschnitts-IDs im GPP String, getrennt durch _ |
IABGPP_HDR_GppString | Der vollständige GPP String |
IABGPP_GppSID | Für den Nutzer geltende Abschnitts-IDs, getrennt durch _, oder -1, wenn keiner gilt |
IABGPP_2_String | IAB TCF EU String, wenn die DSGVO gilt |
IABGPP_5_String | IAB TCF Kanada String, wenn Kanada TCF gilt |
IABGPP_6_String | US Privacy String, wenn der CCPA gilt |
IABGPP_7_String | US National (usnat) String, wenn US State Privacy oder der CCPA gilt |
IABGPP_8_String bis IABGPP_27_String | Der Abschnitt für den Bundesstaat des Nutzers (8 Kalifornien bis 27 Rhode Island), wenn US State Privacy gilt, oder Kalifornien unter dem CCPA, gemäß der Einstellung GPP Sections |
IABUSPrivacy_String | US Privacy String, sobald CCPA aktiviert ist: die Entscheidung des Nutzers in der CCPA Region, sonst 1--- |
Die Schlüssel werden bei jedem Laden der CMP und nach jeder Einwilligungsentscheidung aktualisiert. Welche Nutzer die IABGPP_ Schlüssel erhalten, richtet sich nach GPP Signals in den Projekteinstellungen: Nutzer in Kanada immer (IAB TCF Canada), Nutzer in den USA, wenn US aktiviert ist, und Nutzer in der EU, wenn EU aktiviert ist. Nutzer, für die keine Region gilt, erhalten die Schlüssel ohne Abschnitt, solange US oder EU aktiviert ist, sonst keine Schlüssel.
Apps unterstützen dieselben Optionen für die USA und Kanada wie Websites: CCPA, US State Privacy (mit Bundesstaatenliste, GPP Sections und MSPA Einstellungen) und IAB TCF Kanada. shouldRequestConsent() gibt für Nutzer in Kanada, für die IAB TCF Kanada gilt, true zurück, bis sie eine Entscheidung treffen. US Datenschutz ist ein Opt-out, daher werden Nutzer in den USA nicht von selbst gefragt: Sie sehen das US Banner oder die US Einstellungen, wenn Ihre App die CMP öffnet, zum Beispiel über einen Link zu den Datenschutzeinstellungen. Bis dahin schreibt das SDK, wenn CCPA oder US State Privacy aktiviert ist, für Nutzer in den USA die Standardwerte der US Privacy und GPP Schlüssel, ohne etwas anzuzeigen: kein Widerspruch, oder Widerspruch, wenn auf dem Gerät das Werbe-Tracking deaktiviert ist. US State Privacy ist bei neuen Mobile App Projekten zunächst aus; aktivieren Sie es im Dashboard.
Hat der Nutzer das Werbe-Tracking auf dem Gerät deaktiviert, behandelt die CMP dies als US Widerspruch gegen Verkauf, Weitergabe und zielgerichtete Werbung, so wie Global Privacy Control auf Websites. Unter iOS ist das nicht erlaubtes Tracking in App Tracking Transparency; unter Android eine gelöschte Werbe-ID oder eingeschränktes Werbe-Tracking, gelesen über die Google Play-Dienste, wenn Ihre App sie enthält. Eine Entscheidung, die der Nutzer danach im Banner speichert, hat Vorrang.
Das SDK gibt die gespeicherten Strings auch direkt zurück:
final gppString = await UniConsent.instance.getGPPString();
final gppSid = await UniConsent.instance.getGPPSID();
final usPrivacy = await UniConsent.instance.getUSPrivacyString();
Verfügbar ab SDK Version 26.10.0. Wo eine Region Cookie-Kategorien statt IAB TCF oder der US Richtlinien verwendet, zeigt die CMP ein Banner mit vier Kategorien: Unbedingt erforderlich, Leistung, Funktionalität sowie Targeting oder Werbung. Das gilt für:
Bei Opt-in Kategorien ist zunächst nur „Unbedingt erforderlich“ aktiv, und shouldRequestConsent() gibt true zurück, bis der Nutzer eine Entscheidung trifft, und erneut, nachdem Sie die Konfigurationsversion geändert haben. Bei Opt-out Kategorien sind zunächst alle Kategorien aktiv (Targeting aus, wenn auf dem Gerät in den USA das Werbe-Tracking deaktiviert ist), und die App fragt nicht von selbst: Nutzer ändern sie über Ihren Link zu den Datenschutzeinstellungen. Opt-out gilt für eine Opt-out Regel für andere Länder und, in Apps, für ein Consent Categories Projekt in den USA.
Öffnen Sie die Kategorie-Bildschirme mit CMPStage.categoriesFirstScreen (Banner) und CMPStage.categoriesSecondScreen (Einstellungen). setTestRegion() akzeptiert außerdem BR, CN, ZA, VN und andere Ländercodes, um diese Regionen zu testen.
Verfügbar ab SDK Version 26.10.0. Die benutzerdefinierten Zwecke und benutzerdefinierten Anbieter, die Sie in den Projekteinstellungen des UniConsent Dashboards hinzufügen, erscheinen in den CMP Bildschirmen: die benutzerdefinierten Zwecke in der ersten Ebene und den Einstellungen von IAB TCF sowie in den Einstellungen der Cookie-Kategorien, die benutzerdefinierten Anbieter in der IAB TCF Anbieterliste. In den Einstellungen von CCPA und US State Privacy werden nur sensible benutzerdefinierte Zwecke aufgeführt. In den Einstellungen der Cookie-Kategorien folgen die benutzerdefinierten Anbieter der Kategorie Targeting oder Werbung. Wo IAB TCF nicht gilt (Cookie-Kategorien und die USA), werden die benutzerdefinierten Anbieter schreibgeschützt unter der Anbieterliste im Menü aufgeführt, und in den Einstellungen der Cookie-Kategorien unter Targeting oder Werbung.
Um Ihre eigenen SDKs danach zu starten oder zu stoppen, fragen Sie das SDK, ob die App einen benutzerdefinierten Zweck oder Anbieter jetzt verwenden darf. Die Antwort folgt der Richtlinie des Nutzers, nach denselben Regeln, die die CMP für Tags verwendet:
final cmp = UniConsent.instance;
if (await cmp.isCustomPurposeConsented(1)) {
// das SDK starten, das Ihr benutzerdefinierter Zweck 1 abdeckt
}
final vendorAllowed = await cmp.isCustomVendorConsented(2);
final all = await cmp.getCustomConsents(); // {'purposes': {'1': true}, 'vendors': {'2': false}}
Rufen Sie sie erneut auf, nachdem die CMP geschlossen wurde oder sich die Einwilligung geändert hat. IDs, die das Projekt nicht hat, und alle IDs, bevor das SDK bereit ist, ergeben false.
Die CMP kann die SDKs von Drittanbietern in Ihrer App (Werbenetzwerke, Analyse, Attribution und andere) mit ihrem Unternehmen, ihrem Verwendungszweck und ihrer Datenschutzerklärung auflisten. Nutzer sehen sie unter der Anbieterliste, in allen Regionen schreibgeschützt: Es gibt keine Schalter, und Ihre App schaltet jedes SDK weiterhin anhand der Auswahl des Nutzers für Zwecke oder Cookie-Kategorien ein oder aus.
Um die Liste festzulegen, aktivieren Sie in Step 4: Advanced Features Ihres App-Projekts die Option Enable Third-party SDKs, wählen Sie im Tab Third-party SDKs Ihre SDKs aus oder fügen Sie eigene hinzu, und speichern und veröffentlichen Sie anschließend. In Ihrer App ist dafür kein Code nötig.
setCustomConsent() speichert die Auswahl zu einem benutzerdefinierten Zweck aus einem eigenen Bildschirm Ihrer App, etwa einer Checkbox für das Tracking von E-Mail-Öffnungen; isCustomPurposeConsented() akzeptiert auch die im Dashboard festgelegte ID des Zwecksemail Nutzer-ID wird als email_hash (SHA-256) gesendet; die Adresse selbst wird weder gespeichert noch gesendetgetGPPString(), getGPPSID() und getUSPrivacyString()launchCMP(context, stage:) öffnen; neu: launchCMPIfNeeded(), getGEO() und getGEOState()CMPStage.ccpaFirstScreen und CMPStage.usStateFirstScreen öffnen; neu: setTestRegion(), um die CMP wie für einen Nutzer in einer anderen Region zu testen, etwa KanadaCMPStage.categoriesFirstScreen und CMPStage.categoriesSecondScreengetPolicy(); agreeAll() und rejectAll() speichern außerdem die Cookie-Kategorien, benutzerdefinierten Zwecke und benutzerdefinierten AnbietersetTestRegion() akzeptiert außerdem BR, CN, ZA, VN und andere Ländercodes und gilt auch für getPolicy() und shouldRequestConsent()isCustomPurposeConsented(), isCustomVendorConsented() und getCustomConsents(): die benutzerdefinierten Zwecke und Anbieter, die die App nach der Richtlinie des Nutzers jetzt verwenden darfDatenschutzgesetze, Einwilligung und Compliance, ein paar E-Mails im Monat.