1. Installation

Das ConsentManager SDK ist eine umfassende Lösung zur Verwaltung der Nutzerzustimmung in mobilen Anwendungen. Dieses SDK wurde für die Einhaltung der DSGVO, die Berücksichtigung von Datenschutzpräferenzen der Nutzer und die Transparenz beim Ad-Tracking entwickelt und bietet eine nahtlose Integration für iOS- und Android-Plattformen. Darüber hinaus bietet es Wrapper-Plugins/Bridges für React Native, Flutter und Unity, wodurch es in verschiedenen Entwicklungsumgebungen vielseitig einsetzbar ist.

Dieses Dokument behandelt die Installationsprozedur und die Funktionen, die unseren Kunden zur Verfügung stehen, die Apps mit React Native entwickeln, um über unsere React Native Native Bridge Zugriff auf unser CMP-SDK für das Einwilligungsmanagement zu erhalten. Weitere Details finden Sie in unserer API-Referenzdokumentation. 

1.1 Schritte – Allgemeine Beschreibung

1. Integration und Konfiguration:

   • Integrieren Sie das SDK in Ihre App.
   • Konfigurieren Sie die SDK-Einstellungen entsprechend Ihren Anforderungen.

2. Erstellen einer Instanz und Anzeigen der Einwilligungsschicht:

   • Erstellen Sie beim Start der App eine Instanz der CMPManager Klasse. Diese Instanz übernimmt den Einwilligungsprozess.
   • Das SDK zeigt den Einwilligungsbildschirm bei Bedarf automatisch an.

3. Verarbeitung der Einwilligungsdaten der Nutzer:

   • Sobald die Einwilligungen erfasst sind, werden die Informationen gespeichert und können über verschiedene Eigenschaften und Methoden, die unser SDK bereitstellt, abgefragt werden. Du erhältst Informationen über abgelehnte oder akzeptierte Einwilligungen, Anbieter und Zwecke.

1.2 Konfigurations-API auf einen Blick

setUrlConfig({ id, domain, language, appName, noHash? = false })

setWebViewConfig({
      position? = fullScreen,
      customRect? (required when position = custom),
      cornerRadius? = 5,
      respectsSafeArea? = true,
      allowsOrientationChanges? = true,
      backgroundStyle? = dimmed(black, 0.5)
})

setATTStatus(status) // iOS only; ATTStatus enum (0–3)

• WebViewPosition: FullScreen | HalfScreenTop | HalfScreenBottom | Custom
• BackgroundStyleType (über den BackgroundStyle-Helper):
  • dimmed(color?, opacity?)
  • color(color)
  • blur(blurEffectStyle: light | dark | extraLight)
  • none
• ATTStatus: NotDetermined (0), Restricted (1), Denied (2), Authorized (3)
  

1.3 Integration und Konfiguration

NPM

Wir haben unsere React Native-Brücke sowohl auf NPM (alte und neue Architektur) als auch in unseren öffentlichen Repos veröffentlicht (Tarballs für direkte Verlinkung sind für die alte und neue Architektur verfügbar). Führen Sie diese Zeile in Ihrem Terminal aus:

npm install cm-sdk-react-native-v3           // For the old architecture
npm install cm-sdk-react-native-v3-new-arch  // For the new architecture

Verlinkung (React Native 0.59 und darunter)

Wenn Sie React Native 0.59 oder eine ältere Version verwenden, müssen Sie die nativen Module manuell verknüpfen:

react-native link cm-sdk-react-native-v3

1.4 Instanz erstellen und Einwilligungslayer anzeigen

Sie müssen Ihre CMP-Informationen über die setUrlConfig Methode einrichten, die Ihre CMP-Konfiguration wie Code-ID und Standardsprache verwaltet, sowie setWebViewConfig, die das Aussehen der WebView konfiguriert, in der die Einwilligungsmaske angezeigt wird. Danach kannst du die Methode checkAndOpen(false) , um automatisch die erforderlichen Daten von unserem Server abzurufen und festzustellen, ob der Einwilligungsbildschirm angezeigt werden muss oder nicht. Der boolean Parameter bestimmt, ob die Einwilligungsschicht auf der Einstellungsseite (true), auf der Nutzer ihre Auswahl anpassen können, oder ob die Einwilligungsseite (false) die Seite mit dem Standarddesign Ihrer CMP anzeigt.  

Beispiel:

import {
  setUrlConfig,
  setWebViewConfig,
  setATTStatus,
  BackgroundStyle,
  BackgroundStyleType,
  BlurEffectStyle,
  WebViewPosition,
  ATTStatus,
} from 'cm-sdk-react-native-v3';

const HomeScreen: React.FC = () => {
  const [isLoading, setIsLoading] = useState(true);
  const [toastMessage, setToastMessage] = useState<string | null>(null);

  useEffect(() => {
    initializeConsent();
  }, []);

  const initializeConsent = async () => {
    try {
      await setWebViewConfig({
        position: WebViewPosition.HalfScreenBottom,
        backgroundStyle: BackgroundStyle.blur(BlurEffectStyle.Dark),
        cornerRadius: 25,
        respectsSafeArea: true,
        allowsOrientationChanges: true,
        // customRect is required if you pick WebViewPosition.Custom (iOS only;
        // Android falls back)
      });

      await setUrlConfig({
        id: '<your-Code-id>',
        domain: 'delivery.consentmanager.net',
        language: 'EN',
        appName: 'MyApp',
        noHash: true, // optional; defaults to false
      });

      await CmSdkReactNativeV3.checkAndOpen(false);
      console.log('CMPManager initialized and open consent layer opened if necessary');
    } catch (error) {
      console.error('Error initializing consent:', error);
    } finally {
      setIsLoading(false);
    }
};

Das SDK zeigt an dieser Stelle automatisch den Einwilligungsbildschirm (Cookie-Banner) an, und zwar über ein WebView von unserem SDK erstellten, der die Einwilligungsschicht mit dem Text und den Schaltflächen entsprechend Ihrer CMP-Konfigurationen (ausgewählt über die Code-ID Ihres CMP) anzeigt, die Daten erfasst und die Einwilligungsinformationen im Bereich „NSUserDefaults/UserPreferences“ des Geräts speichert, damit die anderen SDKs sie lesen können.

2. Verarbeitung der Einwilligungsdaten der Nutzer

2.1 Überprüfung der Einwilligungen der Nutzer

Unser SDK bietet verschiedene Methoden zum Abrufen und Überprüfen von Einwilligungsinformationen. Die wichtigste davon ist getUserStatus, wie im folgenden Beispiel dargestellt. Für weitere Informationen, 

// On the example below retrieved from our Demo App, we have some examples 
// of how to check consents from the user, either accepted or rejected. 

const buttons = [
  {
    title: 'Get User Status',
    onPress: () => handleApiCall(
      CmSdkReactNativeV3.getUserStatus,
      (result) => `User Status: ${JSON.stringify(result).substring(0, 100)}...`,
      'Failed to get user status',
      'getUserStatus'
    ),
  },

Weitere Informationen zu den anderen Methoden finden Sie in unserer vollständigen API-Dokumentation zu den zugrunde liegenden nativen iOS- und Android-SDKs. 

2.2 Erneutes Öffnen der Einwilligungsschicht, um die Auswahl der Nutzer zu überprüfen

Damit der Nutzer seine Auswahl überprüfen oder ändern kann, können Sie einfach forceOpen()

const buttons = [
	{
      title: 'Force Open Consent Layer',
      onPress: () => handleApiCall(
        () => CmSdkReactNativeV3.forceOpen(false),
        () => 'Consent Layer opened'
      ),
    },
]

Diese Methode zeigt die Einwilligungsschicht über dieselbe WebView-Instanz an, die in den vorherigen Schritten erstellt wurde. 

2.3 Importieren/Exportieren von Einwilligungsinformationen in andere Quellen

In einigen Fällen kann eine native App Webviews enthalten, um Informationen wie Werbung oder Inhalte anzuzeigen. Um die Einwilligungsinformationen vom SDK an den Webview zu übermitteln und doppelte Cookie-Banner zu vermeiden, können Sie die Einwilligungszeichenfolge mit exportCMPInfo. Dadurch wird der Zustimmungsstring mit der Zustimmung und allen weiteren Daten exportiert, die von der CMP benötigt werden. Du kannst diese Informationen dann an die CMP in deinem Webview weiterleiten, indem du sie der URL hinzufügst, die im Webview aufgerufen wird. Weitere Informationen findest du auf unserer speziellen Seite für diesen Anwendungsfall. 

Ein weiterer Anwendungsfall ist die geräteübergreifende Einwilligung, bei der du die Einwilligung aus einer anderen Quelle auf das Gerät importierst. In diesem Fall kannst du checkAndOpen durch importCMPInfo durch die Einwilligungszeichenfolge ersetzen, die du beispielsweise von der Website abgerufen hast. 

2.4 Ereignis-Listener

Das SDK bietet mehrere Ereignis-Listener, mit denen du auf verschiedene Ereignisse während des Einwilligungsablaufs reagieren kannst. Diese Listener ermöglichen es dir, Benutzerinteraktionen zu verfolgen, Fehler zu behandeln und den Status deiner App mit dem Lebenszyklus der Einwilligungsschicht zu synchronisieren.

Alle Listener geben ein Subscription-Objekt zurück, mit dem der Listener entfernt werden kann, wenn er nicht mehr benötigt wird. Um einen Listener zu entfernen, rufen Sie .remove() für das zurückgegebene Subscription auf.

Verfügbare Ereignis-Listener

addConsentListener(callback)

Dieser Listener wird ausgelöst, wenn der Nutzer seine Einwilligungsentscheidungen übermittelt (entweder durch Akzeptieren, Ablehnen oder Anpassen seiner Einstellungen).

Parameter:

callback: (consent: string, jsonObject: Object) => void
consent: Die Einwilligungszeichenfolge im IAB-TCF-Format
jsonObject: Ein JSON-Objekt mit detaillierten Einwilligungsinformationen

Beispiel:

import { addConsentListener } from 'cm-sdk-react-native-v3';

const consentSubscription = addConsentListener((consent, jsonObject) => {
    console.log('Consent received:', consent);
    console.log('Consent details:', jsonObject);
    // Handle the consent data in your app
});

// To remove the listener later:
// consentSubscription.remove();

addShowConsentLayerListener(callback)
Dieser Listener wird ausgelöst, wenn dem Nutzer die Einwilligungsseite angezeigt wird.

Parameter:

callback: () => void

Beispiel:

import { addShowConsentLayerListener } from 'cm-sdk-react-native-v3';

const showSubscription = addShowConsentLayerListener(() => {
    console.log('Consent layer is now visible');
    // Pause analytics or other tracking activities
});

addCloseConsentLayerListener(callback)

Dieser Listener wird ausgelöst, wenn die Einwilligungsschicht geschlossen wird, unabhängig davon, ob der Nutzer eine Auswahl getroffen oder sie abgelehnt hat.

Parameter:

callback: () => void

Beispiel:

import { addCloseConsentLayerListener } from 'cm-sdk-react-native-v3';

const closeSubscription = addCloseConsentLayerListener(() => {
    console.log('Consent layer has been closed');
    // Resume normal app flow
});

addErrorListener(callback)

Dieser Listener wird ausgelöst, wenn während des Einwilligungsprozesses ein Fehler auftritt, z. B. Netzwerkausfälle, Timeout-Fehler oder Konfigurationsprobleme.

Parameter:

callback: (error: string) => void
error: Eine Zeichenfolge, die den aufgetretenen Fehler beschreibt

Beispiel:

import { addErrorListener } from 'cm-sdk-react-native-v3';

const errorSubscription = addErrorListener((error) => {
    console.error('CMP Error:', error);
    // Handle the error appropriately in your app
    // For example, show a fallback UI or retry logic
});

addClickLinkListener(callback)

Dieser Listener wird ausgelöst, wenn der Nutzer auf einen Link innerhalb der Einwilligungsschicht klickt (z. B. Links zu Datenschutzerklärungen oder Nutzungsbedingungen).

Parameter:

callback: (url: string) => void
url: Die URL, auf die geklickt wurde

Beispiel:

import { addClickLinkListener } from 'cm-sdk-react-native-v3';

const linkSubscription = addClickLinkListener((url) => {
    console.log('User clicked link:', url);
    // Optionally handle the link in a custom way
    // For example, open in an in-app browser
});

3. Integration mit Apple Tracking Transparency (ATT)

Falls Sie Tracking oder Analysen in Ihrer App verwenden, empfehlen wir Ihnen, den Leitfaden zur ATT-Implementierung hier zu lesen.

4. Erstellen eines benutzerdefinierten Layouts

Um eine angepasste Ansicht des WKWebView zu erstellen, beispielsweise durch Ändern der Positionierung oder des Hintergrunds, können Sie die an das ConsentLayerUIConfig-Objekt übergebene Konfiguration wie folgt ändern:

ConsentLayerUIConfig(
    position: .halfScreenTop,
    backgroundStyle: .dimmed(.grey, 0.75),
    cornerRadius: 20,
    respectsSafeArea: false,
    allowsOrientationChanges: true)

5. Protokollierung

Wenn Sie unser iOS-SDK verwenden, kann es vorkommen, dass Sie aus verschiedenen Gründen Log-Informationen debuggen oder analysieren müssen. Die von unserem SDK generierten Logs sind mit dem Tag „CMP“ versehen, sodass Sie die relevanten Logs leicht filtern und anzeigen können. Weitere Informationen finden Sie in diesem Abschnitt unserer Dokumentation.

6. Hinweise zur Plattform

• Expo wird nicht unterstützt
• Android ignoriert derzeit Überschreibungen von backgroundStyle sowie customRect/custom position; es zeigt immer einen abgedunkelten Vollbild-Hintergrund an.
• iOS unterstützt „dimmed“, „color“, „blur“, „none“ und „customRect“.