[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. Unsere Demo-App, die die Anwendungsfälle und eine Implementierung zeigt, die als Ausgangspunkt dienen könnte, finden Sie unter unser Repo. 

1. Installation

Die 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

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.

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:

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: CmpManager? = 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 = CmpManager(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
  }
}    

Das SDK bietet aus Gründen der Flexibilität eine Möglichkeit, die Zustimmungsebene manuell anzuzeigen, allerdings auf Kosten von zwei Seitenaufrufen, einem für die Prüfmethode und einem für die OpenLayer-Methode. Beispiel: 

// code snippet to manually check the need for consent and manually display the consent layer
// ***********************************************************************
// * ATTENTION: although some users might prefer this                    *
// *            Use Case below instead of the automatic way, it          *
// *            comes with a cost of one page view for the check()       *
// *.           method, and another pageview for the openLayer method()  *
// *            so be aware. 											 *
// ***********************************************************************

cmpManager.check(isCached: true) { isConsentRequired in // One page view is counted in case cached consent is expired
    if isConsentRequired {
        // Consent is required, handle accordingly
        DispatchQueue.main.async {
            // Update UI or show consent dialog
            cmpManager?.openLayer()                      // One page view is counted here
        }
    } 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: CmpManager? = 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()
        }
    }
}

3. Verwendung des SDK

Überprüfung auf Einwilligung

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

Weitergabe von Zustimmungsinformationen an andere Quellen

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:

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: 

// Importing consent data if you like
cmpManager.importCmpString("${your base64 encoded consentString}");

// ... Your code here ...

// Exporting Consent data 
let consentString : String = cmpManager.exportCmpString()

Der ConsentString sollte Base64-codiert sein.

Interne App-Links und Domain-Whitelist

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.