[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
-
Integration und Konfiguration:
- Integrieren Sie das SDK in Ihre App.
- Konfigurieren Sie die SDK-Einstellungen entsprechend Ihren Anforderungen.
-
Erstellen einer Instanz:
- Erstellen Sie beim Start der App eine Instanz von
CMPConsentTool
Klasse. Diese Instanz übernimmt den Einwilligungsprozess.
- Erstellen Sie beim Start der App eine Instanz von
-
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.
-
Anzeigen des Einwilligungsbildschirms:
- Das SDK zeigt bei Bedarf automatisch den Einwilligungsbildschirm an
CMPConsentTool
Instanz wird erstellt.
- Das SDK zeigt bei Bedarf automatisch den Einwilligungsbildschirm an
-
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.
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
- Öffnen Sie den Swift-Paketmanager.
- Gehen Sie zu
File
>Swift Packages
>Add Package Dependency
. - 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 aufNext
. - 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 aufNext
. - 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. KlickenFinish
um den Prozess abzuschließen. - 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:
Name |
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:
// 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 CmpConfig
kö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.