UniConsent CMP SDK für Flutter in mobile Apps integrieren

UniConsent CMP ist ein Paket zur Verwaltung der GDPR IAB TCF 2.3 Einwilligung in Flutter-Apps. Eine Demo-App mit integrierter UniConsent CMP finden Sie im Verzeichnis "uniconsent_demo".

Voraussetzungen

• UniConsent CMP-Tarif mit Unterstützung für mobile Apps
• UniConsent CMP SDK-Paket (beim Support anfragen)

Erste Schritte

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

Einwilligungs-UI anpassen

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.

Schritt 1: Markenstyling im Dashboard

Gehen Sie zu Projects → Projekt auswählen → Settings → Step 5: UI & Style Settings, um folgende Einstellungen vorzunehmen:

• Main Button Colour — Stellen Sie die Farbe der primären Aktionstaste passend zu Ihrer Marke ein
• Main Button Text Colour — Passen Sie die Textfarbe auf der primären Taste für bessere Lesbarkeit an
• Background Colour — Stellen Sie die Hintergrundfarbe des Banners ein, damit es sich in Ihre App einfügt
• Text Colour — Stellen Sie sicher, dass der Fließtext ausreichend Kontrast hat

Schritt 2: Erweitertes Styling mit benutzerdefiniertem CSS (Optional)

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.

Verwendung

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

Event Handler

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 angezeigt
• CMPEventType.uiClose — Einwilligungs-UI wird geschlossen

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

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

Einwilligung an WebView synchronisieren

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

Exportierte Typen

Die folgenden Typen sind beim Import von package:uniconsent/uniconsent.dart verfügbar:

• UniConsent — Haupt-SDK-Singleton
• UniConsentInfo — Basis-Einwilligungsdaten (sdkId, tcString, gdprApplies, vendorListVersion, etc.)
• ConsentInfo — erweitert UniConsentInfo mit Einwilligungslisten auf Zweckebene
• DataUsagePurpose — Enum der IAB TCF 2.3 Zweck-IDs
• KVDBKeys — 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 (sdkInit, ready, uiDisplay, uiClose)
• CMPEvent — Ereignisobjekt mit einer type-Eigenschaft
• CMPEventCallback — Typedef für den subscribe()-Callback
• LogLevel — debug / prod
• ConsentCallback — Typedef für den onConsentChanged-Callback
• UniConsentCMPContent — das Kern-CMP-Widget für benutzerdefinierte Layouts

Hinweise

1. Nutzer sollten die Möglichkeit haben, über einen Button oder Link "Datenschutzeinstellungen" im Einstellungsbereich Ihrer App die CMP-UI zu öffnen.
2. Sie können die Funktion shouldRequestConsent() verwenden, um zu prüfen, ob eine neue Einwilligung basierend auf dem Status angefordert werden sollte. Zeigen Sie die CMP-UI bei Bedarf an, wenn ein Nutzer die Anwendung öffnet.