Info
Inhalt

[iOS] 1. consentmanager SDK-Integration

In diesem Dokument finden Sie allgemeine Informationen zur Integration unseres SDK in Ihr Projekt. Weitere Einzelheiten entnehmen Sie bitte unserer API-Referenz Dokumentation. 

1. Installation

Das consentmanager SDK für iOS-Apps implementiert und bietet Funktionen, um den Benutzer über den Datenschutz zu informieren und die Zustimmung des Benutzers einzuholen und einzuholen. Es ermöglicht App-Entwicklern, das einfach zu integrieren consentmanager Service in ihre App.

Schritte – Beschreibung auf hoher Ebene

  1. Integration und Konfiguration:

    • Integrieren Sie das SDK in Ihre App.
    • Konfigurieren Sie die SDK-Einstellungen entsprechend Ihren Anforderungen.
  2. Erstellen einer Instanz:

    • Erstellen Sie beim Start der App eine Instanz von CMPConsentTool Klasse. Diese Instanz übernimmt den Einwilligungsprozess.
  3. SDK-Initialisierung:
    • Sobald die Instanz bereit ist, ruft das SDK automatisch die erforderlichen Informationen von der Instanz ab consentmanager Server, um sich auf den Betrieb vorzubereiten.
  4. Anzeigen des Einwilligungsbildschirms:

    • Das SDK zeigt bei Bedarf automatisch den Einwilligungsbildschirm an CMPConsentTool Instanz wird erstellt.
  5. Verarbeitung personenbezogener Daten:

    • Sobald die Einwilligungen eingeholt wurden, werden die Informationen gespeichert und stehen für Abfragen über verschiedene Eigenschaften und Methoden zur Verfügung, die von unserem SDK bereitgestellt werden. Sie erhalten Informationen über abgelehnte oder akzeptierte Einwilligungen, Anbieter, Zwecke usw.

Indem Sie diese Schritte befolgen, stellen Sie sicher, dass Ihre App den Einwilligungsanforderungen entspricht und dass die Nutzereinwilligung ordnungsgemäß verwaltet und gespeichert wird.

Consent Manager Anbieter-SDK-Sequenzdiagramm

Um die oben genannten Schritte zu veranschaulichen, sehen wir uns im Diagramm unten drei mögliche SDK-Sequenzabläufe an. 

1. Beim Erstellen einer Instanz mit dem initialisieren Funktion gibt es zwei mögliche Ergebnisse. Der erste Fall besteht darin, dass die Consentmanger-API das SDK darüber informiert, dass das CMP nicht geöffnet wird, was das auslöst OnCmpNotOpenedCallback. Das zweite Ergebnis ist, wenn die Zustimmungsebene geöffnet wird, sodass der Benutzer damit interagieren kann, und dies löst die aus OnOpenCallback. Sobald der Benutzer seine Zustimmung erteilt und die Zustimmung verarbeitet wird, wird die OnCmpCloseCallback wird genannt.

Bitte beachten Sie, dass die OnErrorCallback wird durch die rot gestrichelten Pfeillinien dargestellt, um Beispiele dafür zu liefern, wann während des Prozesses Fehler auftreten können.

Initialize-Cmp-Sequence-Diagram.png

2. Erstellen einer Instanz und Aufrufen der openAndCheckConsent Funktionen führen zu einem ähnlichen Prozess. Der Unterschied besteht darin, dass Sie durch die Entkopplung der Erstellung der Instanz und der Prüfung für die Consentmanger-API die Möglichkeit erhalten, Geschäftslogik hinzuzufügen und mit der Bibliotheks-API zu interagieren.

3. Erstellen einer Instanz und Aufrufen der offeneSchicht Die Funktion öffnet die Ebene, ohne die zu überprüfen consentmanager, wenn es nötig ist. Bei bereits erteilter Einwilligung werden dem Nutzer die Optionen und Einstellungen aufgezeigt. Der Prozessablauf wird wie folgt aussehen:

openlayer-Cmp-Sequenzdiagramm-.png

Weitere Informationen zu unserer SDK-Versionsübersicht und dem Änderungsprotokoll finden Sie unter diesen Link.

Installation über Cocoapod

Sie können das installieren consentmanager SDK durch Hinzufügen CmpSdk zu Ihrem Podfile, wie im folgenden Beispiel erläutert:

target 'YourProject' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!
  pod 'CmpSdk'

  target 'YourProjectTests' do
    inherit! :search_paths
     # Pods for testing
  end
  
...
      
end

Sobald dies erledigt ist, müssen Sie ausführen pod install in Ihrem Projektverzeichnis, um das zu installieren consentmanager SDK. Danach öffnen Sie bitte die *.xcworkspace und bauen. 

Nachdem Sie alle Schritte ausgeführt haben, sollte Ihre Abhängigkeit installiert sein, und Sie können fortfahren und sie in Ihrem Projekt verwenden.

Installation über Swift Package Manager

  1. Öffnen Sie den Swift-Paketmanager.
  2. Gehen Sie zu File > Swift Packages > Add Package Dependency.
  3. Fügen Sie die SDK-Repository-URL hinzu
    Sie sehen nun ein neues Fenster, in dem Sie die URL des SDK-Repositorys eingeben können. Die meisten SDKs werden auf GitHub gehostet, daher sieht die URL oft so aus
    https://github.com/iubenda/cm-sdk-xcframework.git
    Klicken Sie nach Eingabe der URL auf Next.
  4. Wählen Sie die SDK-Version aus
    SPM ruft nun das Repository ab und fordert Sie auf, eine Version auszuwählen.
    Sie können das Paket hinzufügen, indem Sie eine Versionsregel auswählen:
    - Up to Next Major: Dadurch wird das Paket auf die nächste Hauptversion aktualisiert. Dies ist die empfohlene Option, da sie Updates hinzufügt, die keine wichtigen Änderungen enthalten.
    - Up to Next Minor: Dadurch wird das Paket auf die nächste Nebenversion aktualisiert.
    - Exact: Dadurch wird das Paket an eine bestimmte Version gebunden. Es werden keine Updates installiert.
    Wählen Sie die Version aus, die Sie verwenden möchten, und klicken Sie auf Next.
  5. Fügen Sie das SDK zu Ihrem Ziel hinzu
    Wählen Sie im nächsten Bildschirm die Ziele aus, denen Sie die Paketabhängigkeit hinzufügen möchten. Ziele sind normalerweise Ihre App und alle Tests, die Sie möglicherweise durchführen. Klicken Finish um den Prozess abzuschließen.
  6. Importieren Sie das SDK
    Nachdem das SDK nun zu Ihrem Projekt hinzugefügt wurde, müssen Sie es importieren, um es verwenden zu können. Gehen Sie zu der Datei, in der Sie das SDK verwenden möchten, und fügen Sie oben die folgende Importanweisung hinzu:
import CmpSdk

2. Initialisieren des SDK

Innerhalb des App-Starts (Ihre viewDidLoad Funktion), müssen Sie eine Instanz der Klasse erstellen CMPConsentTool. Das initialize() Die Funktion ruft automatisch die erforderlichen Daten von unserem Server ab und bestimmt, ob der Einwilligungsbildschirm angezeigt werden muss oder nicht. Wenn dies der Fall ist, zeigt das SDK an dieser Stelle automatisch den Einwilligungsbildschirm an, erfasst die Daten und stellt sie der App zur Verfügung. Die Instanz kann dann verwendet werden, um Einwilligungsdetails vom SDK abzurufen, um sie in der App zu verwenden.

Beispiel einer Initialisierung unter Verwendung des automatischen Verhaltens von initialize() Verfahren:

class ViewController: UIViewController {

  // Usual implementation of a View Controller
  
  var cmpManager: CMPConsentTool? = nil

  override func viewDidLoad() {

      super.viewDidLoad()

      // Configure your CMP
      let cmpConfig: CmpConfig = CmpConfig.shared.setup(
                                          withId: "<YOUR-CONSENTMANAGER-APP-ID>", // example: a000aaaaa1a 
                                          domain: "<YOUR-CONSENTMANAGER-APP-DOMAIN>", // example: delivery.consentmanager.net 
                                          appName: "<YOUR-CONSENTMANAGER-APP-NAME>", // example: testApp
                                          language: "<YOUR-CONSENTMANAGER-APP-LANGUAGE"); // example: DE

      // You can also determine log levels or ask for Apple's App Tracking Transparency, for example
      cmpConfig.logLevel = CmpLogLevel.verbose;
      cmpConfig.isAutomaticATTRequest = true;

      // Then you pass the cmpConfig to set up and initialize the instance of our SDK		
      cmpManager = CMPConsentTool(cmpConfig: cmpConfig)
              .withErrorListener(onCMPError)
              .withCloseListener(onClose)
              .withOpenListener(onOpen)
              .withOnCMPNotOpenedListener(onCMPNotOpened)
              .withOnCmpButtonClickedCallback(onButtonClickedEvent)
              .initialize()  // This method will trigger the webview loading to collect consent, if necessary
  }
}    

Aus Gründen der Flexibilität bietet das SDK eine Möglichkeit, die Zustimmungsebene manuell anzuzeigen, wie unten gezeigt: 

.
.
.
// code snippet to manually check the need for consent and manually display the consent layer
cmpManager.check(isCached: true) { isConsentRequired in
    if isConsentRequired {
        // Consent is required, handle accordingly
        DispatchQueue.main.async {
            // Update UI or show consent dialog
            cmpManager?.openLayer()
        }
    } else {
        // Consent is not required, proceed with application logic
    }
}

Bitte beachten Sie, dass Sie unbedingt die initialize() Methode im SDK in der viewDidLoad-Methode, wenn Sie sich für die automatische Initialisierung entscheiden. Andernfalls ist die Ansicht möglicherweise nicht einsatzbereit und das SDK schlägt möglicherweise fehl. Stellen Sie außerdem sicher, dass Sie die richtigen Konfigurationsdaten verwenden. Die Konfigurationsdaten finden Sie in Ihrem consentmanager Konto bei Menü > CMPs > Code für Apps abrufen > Code-ID

SwiftUI

Um das SDK in eine SwiftUI-Umgebung zu integrieren, müssen Sie eine bereitstellen UIViewController die in a eingewickelt ist UIViewControllerRepresentable. Weitere Informationen finden Sie auf der offiziellen Seite Apfeldokumentation. Stellen Sie vor der Integration des SDK sicher, dass Sie das Modul bereits in Ihr Projekt integriert haben. 

1. Wir beginnen mit der Erstellung eines gewöhnlichen UiViewControllers ähnlich den Beispielen für Swift/Objective C

import UIKit
import CmpSdk

class CmpViewController: UIViewController {

    var cmpManager: CMPConsentTool? = nil
            
    override func viewDidLoad() {
      .
      .
      .
      // Implement it like the previous example
    }
    
    /**
     * Show consent button was clicked
     */
    @objc func onShowConsentClicked(sender: UIButton!) {
        cmpManager!.openView()
    }
}

2. Um den Controller im SwiftUI Sie müssen ein UIViewControllerRepresentable erstellen, das die instanziiert CmpViewController:

import SwiftUI

struct CmpViewControllerRepresentable: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        let cmpViewController = CmpViewController()
        
        return cmpViewController
    }
    
    func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
    }
}

3. Jetzt können wir die verwenden ControllerView im SwiftUI-Kontext:

import SwiftUI

@main
struct cmpApp: App {
    var body: some Scene {
        WindowGroup {
            CmpViewControllerRepresentable()
        }
    }
}

Ein Beispielprojekt wird bereitgestellt hier

3. Verwendung des SDK

Um zu überprüfen, ob ein Anbieter oder ein Zweck eine Einwilligung hat, können Sie die beiden folgenden Methoden verwenden:

if cmpManager!.hasPurposeConsent("52")
{
    if cmpManager!.hasVendorConsent("s26")
    {
        //Add your logic here
    }
}

Beide Methoden hasPurposeConsent und hasVendorConsent erfordern zwei Parameter:

  • id - Zeichenfolge der Hersteller- oder Zweck-ID. Bitte beachten Sie, dass Hersteller-IDs unterschiedliche Formate haben können ("123", "s123" und "c123") Menü> Anbieter und Menü> Zwecke in Ihrem consentmanager Konto.
  • isIABVendor / isIABPurpose - Wenn der Anbieter oder Zweck ein Anbieter / Zweck ist, der dem IAB-TCF-Standard entspricht, müssen Sie ein true festlegen, andernfalls ein false.

Denken Sie daran: Alle Anbieter, die nicht zum IAB gehören, haben IDs, die mit einem "s" oder "c" beginnen (z. B. "s123"). Anbieter, die zum IAB gehören, haben IDs, die nicht mit einem "s" oder "c" beginnen.

Öffnen Sie den Zustimmungsbildschirm erneut

Damit der Benutzer die Auswahl ändern kann, können Sie einfach anrufen openView()

cmpManager!.openView()

In einigen Fällen kann eine native App Webansichten enthalten, um bestimmte Dinge wie Werbung oder Inhalte anzuzeigen. Um die Einwilligungsinformationen vom SDK an die Webansicht zu übermitteln, nutzen Sie bitte die Funktion:

consentData = cmpManager.exportCmpString();

Dadurch werden die Zustimmungsinformationen und alle weiteren Daten exportiert, die vom CMP benötigt werden. Sie können diese Informationen dann an das CMP in Ihrer Webansicht übergeben, indem Sie sie der in der Webansicht aufgerufenen URL hinzufügen:

myWebView.loadURL("https://mywebsite.com/....#cmpimport=" + consentData);

/** to pass the att status you can use the cmpatt parameter (1=accepted, 2=declined) */

myWebView.loadURL("https://mywebsite.com/....#cmpimport=" + consentData + "&cmpatt=1");

Integration mit Apple Tracking Transparency (ATT)

Falls Sie Tracking oder Analysen in Ihrer App verwenden, empfehlen wir Ihnen, die Anleitung auf zu lesen ATT-Implementierung hier.

Erstellen eines benutzerdefinierten Layouts

Für ein benutzerdefiniertes Layout gibt es zwei Rückruffunktionen, die den viewController und den uiView bereitstellen. Im unten gezeigten Beispiel können Sie sehen, wie Sie das Layout anpassen:

        let cmpLayout = CmpLayout.default()
        cmpLayout?.cornerRadius = 10.0
        cmpLayout?.customLayout = CGRect(x: 0, y: 0, width: 200, height: 300)
        cmpManager = CMPConsentTool(cmpConfig: cmpConfig)
            .withCmpViewControllerConfigurationBlock({ viewController in
                viewController?.modalPresentationStyle = .formSheet
                //example of customizing controller
            })
            .withCmpViewConfigurationBlock({ uiView in
                cmpLayout?.apply(to: uiView)
                // or use your own uiView logic 
            })
1. mitCmpViewControllerConfigurationBlock

Mit dieser Funktion können Sie den Präsentationsstil des View Controllers für die SDK-Komponente anpassen. Durch die Übergabe eines Konfigurationsblocks können Sie verschiedene Eigenschaften des View Controllers ändern, beispielsweise seinen modalen Darstellungsstil.

Beispiel: 

.withCmpViewControllerConfigurationBlock({ viewController in
	// Ensure the viewController is not nil before applying the configuration
	viewController?.modalPresentationStyle = .currentContext
	})
2. mitCmpViewConfigurationBlock

Mit dieser Funktion können Sie die UI-Ansicht für die SDK-Komponente anpassen. Durch die Übergabe eines Konfigurationsblocks können Sie verschiedene Eigenschaften der Ansicht ändern, beispielsweise deren Layout und Erscheinungsbild

Beispiel:

.withCmpViewConfigurationBlock({ uiView in
	// Configure the uiView to display as a half-screen top layout
	CmpUIConfig.configureHalfScreenTop(for: uiView)
    })

Benutzerdefinierte Ereignislistener

Um zusätzliche Prozesslogik hinzuzufügen, können Sie Event Listener verwenden. Folgende Ereignis-Listener sind verfügbar:

Name und Vorname

Tritt auf

 

CmpOpenListener

Listener für Ereignis, wenn CMP geöffnet wird

CmpCloseListener

Listener für Ereignis, wenn CMP geschlossen ist

CmpNotOpenedListener

Listener für Ereignis, wenn CMP nicht geöffnet werden muss

CmpErrorListener

Der Listener wird aufgerufen, wenn beim Aufruf des Servers oder beim Anzeigen der Ansicht ein Fehler auftritt.

CmpButtonClickedListener

Listener für Ereignisse, wenn auf die Schaltfläche geklickt wird und die Zustimmungsebene geschlossen wird

CmpATTrackingStatusChangedListener

Listener für ATTracking-Status geändert

onCmpUpdateGoogleConsent

Listener für Änderungen des Zustimmungsmodus

Zustimmung zum Importieren/Exportieren

Zum Importieren oder Exportieren der Einwilligung können Sie die Funktionen nutzen exportCMPString() und importCMPString(). Überprüfen Sie das folgende Beispiel: 

Der ConsentString sollte Base64-codiert sein.

Um die Funktionalität zu implementieren, bei der bestimmte Domänen auf die Whitelist gesetzt werden und beim Zugriff innerhalb der Consent Platform (CMP) WebView nicht in einem externen Browser wie Safari, sondern innerhalb der WebView selbst geöffnet werden, können Sie einen Rückrufmechanismus implementieren, um benutzerdefinierte Aktionen basierend auf dem auszuführen Domäne, z. B. Öffnen eines anderen ViewControllers:

cmpConfig.domainWhitelist = ["add your domains to be whitelisted"]
        
cmpManager.withOnCmpLinkClickListener({ url, decisionHandler in
                //check URL and add the nav action
                decisionHandler!.pointee = WKNavigationActionPolicy.allow
                decisionHandler!.pointee = WKNavigationActionPolicy.cancel
                // return shouldCloseWebView (true) or stay open (false)
                return true
            })        

Protokollierung

Wenn Sie unser iOS SDK verwenden, müssen Sie möglicherweise Protokollinformationen für verschiedene Zwecke debuggen oder analysieren. Die von unserem SDK generierten Protokolle sind mit „Cmp:“ gekennzeichnet, sodass Sie einfach nur die relevanten Protokolle filtern und anzeigen können. Diese Anleitung enthält Schritt-für-Schritt-Anleitungen für den Zugriff auf diese Protokolle in Xcode.

Suchen Sie nach dem Tag

In der Debug-Konsole von Xcode können Sie nach Protokollen suchen, die speziell mit „Consent“ oder „CMP“ gekennzeichnet sind, um die von unserem SDK generierten Protokolle zu isolieren.

Optional: Passen Sie die Ausführlichkeitsstufe an

In CmpConfigkönnen Sie den Ausführlichkeitsgrad für detailliertere Protokolle anpassen.

cmpConfig.isDebugMode = true   
cmpConfig.logLevel = CmpLogLevel.debug
  • Ermöglicht detailliertere Protokolle
  • Nützlich zum Debuggen und Analysieren.

Durch Anpassen der Ausführlichkeitsstufe erhalten Sie umfassendere Protokollinformationen, die das Debuggen und die Analyse des Verhaltens unseres SDK in Ihrer Anwendung unterstützen.

 

Nach oben