UniConsent CMP SDK für iOS in mobile Apps integrieren

UniConsent CMP ist ein Paket zur Handhabung der DSGVO IAB TCF 2.3-Einwilligungsverwaltung unter iOS. Eine Demo-App mit integriertem UniConsent CMP finden Sie im Verzeichnis "UniConsentDemo".

Voraussetzungen

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

Erste Schritte

Fügen Sie UniConsent.xcframework in Ihr Projekt ein. Setzen Sie unter General > Frameworks, Libraries, and Embedded Content Ihres Targets UniConsent.xcframework auf Embed & Sign.

Einwilligungs-UI anpassen

Bevor Sie das SDK integrieren, passen Sie das Erscheinungsbild des Einwilligungsbanners im UniConsent Dashboard an Ihre Marke an, um die Einwilligungsrate zu optimieren.

Schritt 1: Markengestaltung im Dashboard

Gehen Sie zu Projects → Projekt auswählen → Settings → Step 5: UI & Style Settings, um Folgendes zu konfigurieren:

• Main Button Colour -- Legen Sie die Farbe der primären Aktionsschaltfläche passend zu Ihrer Marke fest
• Main Button Text Colour -- Passen Sie die Textfarbe auf der primären Schaltfläche für bessere Lesbarkeit an
• Background Colour -- Legen Sie die Hintergrundfarbe des Banners fest, damit es zu Ihrer App passt
• Text Colour -- Stellen Sie sicher, dass der Fließtext einen angemessenen Kontrast aufweist

Schritt 2: Erweiterte Gestaltung 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 das Banner nativ in Ihrer App wirkt 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 nativ in Ihrer App wirkt, erzielt in der Regel höhere Einwilligungsraten. Nutzer reagieren eher positiv auf ein Banner, das dem erwarteten Look and Feel entspricht.

Verwendung

Um UniConsent CMP in Ihrer App zu verwenden, folgen Sie diesen Schritten:

Initialisieren Sie die CMP mit einer App-ID von Ihrem Account-Manager:

import UniConsent

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Init CMP with appId
    UniConsentCMP.shared.initialize(apiId: "YOUR_APP_ID_CHANGE_THIS")
    return true
}

CMP-UI anzeigen:

// Display CMP as full-screen modal (default)
UniConsentCMP.shared.setUIStage(.GDPRFirstScreen)
UniConsentCMP.shared.launchCMP(rootVC: self)

// Display CMP as a modal bottom sheet
UniConsentCMP.shared.launchCMP(rootVC: self, displayMode: .modalSheet)

// Display CMP as a center dialog
UniConsentCMP.shared.launchCMP(rootVC: self, displayMode: .dialog)

Verfügbare Anzeigemodi (CMPDisplayMode):

• .fullScreen -- Vollbild-Modal-Darstellung (Standard)
• .modalSheet -- Bottom Sheet mit Drag-Handle (iOS 15+)
• .dialog -- Zentrierter Dialog mit abgedunkeltem Hintergrund

Event-Handler

Überwachen Sie SDK-Lebenszyklusereignisse mit CMPEventHandler. Dies ist die empfohlene Methode, um zu erfahren, wann das SDK die Initialisierung abgeschlossen hat, wann die UI angezeigt wird und wann sie geschlossen wird.

Verfügbare Ereignisse (CMPEventType):

• .sdkInit -- SDK-Initialisierung gestartet
• .ready -- SDK-Initialisierung abgeschlossen (GEO, Konfiguration und Anbieter geladen)
• .uiDisplay -- Einwilligungs-UI wird angezeigt
• .uiClose -- Einwilligungs-UI wird geschlossen

Abonnieren Sie Ereignisse vor dem Aufruf von initialize(), um alle Ereignisse zu empfangen:

import UniConsent

@main
class AppDelegate: UIResponder, UIApplicationDelegate, CMPEventHandler {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        UniConsentCMP.shared.subscribe(self)
        UniConsentCMP.shared.initialize(apiId: "YOUR_APP_ID")
        return true
    }

    func handle(event: CMPEvent) {
        switch event.type {
        case .ready:
            // SDK is ready — check consent and launch CMP if needed
            if UniConsentCMP.shared.shouldRequestConsent() {
                // launch CMP from your root view controller
            }
        case .uiClose:
            // User finished interacting with consent UI
            print("TC String:", UniConsentCMP.shared.getTCString())
        default:
            break
        }
    }
}

Sie können auch von einem View Controller aus abonnieren:

class ViewController: UIViewController, CMPEventHandler {

    override func viewDidLoad() {
        super.viewDidLoad()
        UniConsentCMP.shared.subscribe(self)
    }

    func handle(event: CMPEvent) {
        switch event.type {
        case .uiDisplay:
            print("CMP UI is now visible")
        case .uiClose:
            print("Consent given, vendor 1 allowed:", UniConsentCMP.shared.isAllowVendorById(vendorId: 1))
        default:
            break
        }
    }
}

Zum Abbestellen:

UniConsentCMP.shared.unsubscribe(self)

CMPUIDelegate (Legacy)

Sie können auch über CMPUIDelegate auf das Schließen der Einwilligungsoberfläche reagieren:

class ViewController: UIViewController, CMPUIDelegate {

    func showCMP() {
        UniConsentCMP.shared.view.delegate = self
        UniConsentCMP.shared.setUIStage(.GDPRFirstScreen)
        UniConsentCMP.shared.launchCMP(rootVC: self, displayMode: .modalSheet)
    }

    func onDismiss() {
        // Called when the user closes the consent UI
        print("TC String:", UniConsentCMP.shared.getTCString())
    }
}

Automatisch prüfen, ob die Einwilligung abgelaufen ist, wenn die vendorList aktualisiert wird:

// Automatic check if consent is expired when vendorList updates
if UniConsentCMP.shared.shouldRequestConsent() {
    UniConsentCMP.shared.launchCMP(rootVC: self)
}

Den tcString bei Bedarf abrufen:

// Get tcString if required
UniConsentCMP.shared.getTCString()

Den Einwilligungsstatus auslesen:

// Check consent for a specific IAB purpose
UniConsentCMP.shared.isAllowPurposeById(purposeId: 1)

// Check consent for a specific IAB vendor
UniConsentCMP.shared.isAllowVendorById(vendorId: 1)

// Get all allowed purpose/vendor IDs
UniConsentCMP.shared.getAllowedPurposeIds()
UniConsentCMP.shared.getAllowedVendorIds()

// Check if GDPR applies
UniConsentCMP.shared.gdprApplies

// Check if any consent has been given
UniConsentCMP.shared.isConsentGiven()

Einwilligungsstatus bei Bedarf zurücksetzen:

// Reset consent status if required
UniConsentCMP.shared.clearConsentData()

Einwilligung an WebView synchronisieren

Wenn Ihre App eine WKWebView öffnet, die eine Webseite mit dem UniConsent CMP-Tag lädt, können Sie den nativen Einwilligungsstatus übergeben, damit der CMP-Tag die bestehende Einwilligung erkennt und das Banner nicht erneut anzeigt.

Rufen Sie syncConsent(to:) vor dem Laden der Webseite auf:

import WebKit
import UniConsent

let webView = WKWebView(frame: .zero, configuration: WKWebViewConfiguration())

// Inject native consent before page load
UniConsentCMP.shared.syncConsent(to: webView)

// Then load your web page
webView.load(URLRequest(url: URL(string: "https://example.com")!))

Objective-C

// Initialize with event handler
@interface AppDelegate () <CMPEventHandler>
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[UniConsentCMP shared] subscribe:self];
    [[UniConsentCMP shared] initializeWithApiId:@"YOUR_APP_ID"];
    return YES;
}

- (void)handleWithEvent:(CMPEvent *)event {
    switch (event.type) {
        case CMPEventTypeReady:
            NSLog(@"CMP ready");
            break;
        case CMPEventTypeUiClose:
            NSLog(@"TC String: %@", [[UniConsentCMP shared] getTCString]);
            break;
        default:
            break;
    }
}

@end

// Display CMP (full screen by default)
[UniConsentCMP.shared launchCMPWithRootVC:self];

// Display CMP with a specific display mode
// Use CMPDisplayModeFullScreen, CMPDisplayModeModalSheet, or CMPDisplayModeDialog
[UniConsentCMP.shared launchCMPWithRootVC:self displayMode:CMPDisplayModeModalSheet];

Consent Mode

Standard-Einwilligungsstatus-KV einrichten:

<key>FIREBASE_ANALYTICS_COLLECTION_ENABLED</key> <false/>
<key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_ANALYTICS_STORAGE</key> <false/>
<key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_STORAGE</key> <false/>
<key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_USER_DATA</key> <false/>
<key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_PERSONALIZATION_SIGNALS</key> <false/>

Analytics basierend auf den Einwilligungs-Flags steuern:

// SDK Version <= 25.6.1
public func onDismiss() {

    if(UniConsentCMP.shared.isAllowPurposeById(purposeId: 1)) {
        Analytics.setConsent([
          .analyticsStorage: .granted,
          .adStorage: .granted,
          .adUserData: .granted,
          .adPersonalization: .granted,
        ])
        Analytics.setAnalyticsCollectionEnabled(true);
    } else {
        Analytics.setConsent([
          .analyticsStorage: .denied,
          .adStorage: .denied,
          .adUserData: .denied,
          .adPersonalization: .denied,
        ])
        Analytics.setAnalyticsCollectionEnabled(false);
    }

    // other logics such as send analytics events
}

Weitere Informationen finden Sie unter Consent Mode für Apps einrichten

Hinweise

1. Nutzer sollten die Möglichkeit haben, über eine Schaltfläche oder einen Link "Datenschutzeinstellungen" im Einstellungsbereich Ihrer Anwendung auf die CMP-UI zuzugreifen.
2. Sie können die Funktion shouldRequestConsent() verwenden, um zu prüfen, ob basierend auf dem Status eine neue Einwilligung angefordert werden sollte. Zeigen Sie die CMP-UI bei Bedarf an, wenn ein Nutzer die Anwendung öffnet.
3. Ab SDK-Version 25.6.1 müssen Sie Einwilligungsoptionen für FirebaseAnalytics oder bestimmte unterstützte AAP-SDKs nicht mehr manuell senden -- diese werden automatisch vom SDK verarbeitet. Weitere Informationen finden Sie unter Was sind Google AAP und Google MMP für mobile Apps?.