[iOS] 1. consentmanager SDK-Integration

Der 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.

So funktioniert's

1. Integrieren Sie das SDK in die App und konfigurieren Sie die SDK-Einstellungen
2. Sobald das SDK in eine App eingebunden ist, stellt das SDK Funktionen für den App-Entwickler bereit, um Zustimmungsdaten abzurufen
3. Sobald die App gestartet wird, ruft das SDK automatisch Informationen von der ab consentmanager Server, um das SDK für die Verwendung vorzubereiten.
4. Es wird empfohlen, dass die App beim Start der App eine Klasseninstanz erstellt CMPConsentTool. Sobald dies erstellt wurde, zeigt das SDK bei Bedarf automatisch den Zustimmungsbildschirm an.
5. Wenn die App personenbezogene Daten verarbeiten möchte, sollte sie das SDK "fragen", ob die Zustimmung für den jeweiligen Zweck und Anbieter erteilt wurde.

Installation über Cocoapod

Bibliothek mit Cocoapod hinzufügen

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

Gehen Sie zu File > Swift Packages > Add Package Dependency.

2. 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.

3. 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.

4. 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 Sie Finish um den Prozess abzuschließen.

5. 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

Initiieren Sie das SDK

Mit dem App-Start (in der Regel Ihre viewDidLoad-Funktion) können Sie sollen Erstellen Sie eine Instanz der Klasse CMPConsentTool. Dadurch werden automatisch die erforderlichen Daten von unserem Server abgerufen und festgestellt, ob der Zustimmungsbildschirm angezeigt werden muss oder nicht. In diesem Fall zeigt das SDK an dieser Stelle automatisch den Zustimmungsbildschirm an, sammelt die Daten und stellt die Daten der App zur Verfügung. Die Instanz kann dann verwendet werden, um Zustimmungsdetails vom SDK abzurufen und in der App zu verwenden.

/** Initialize with CmpConfig */
let cmpConfig : CmpConfig = CmpConfig.init()
CmpConfig.setValues(myCmpConfig.domain, addCodeId: myCmpConfig.appId, addAppName: myCmpConfig.appName, addLanguage: myCmpConfig.language)
cmpConsentTool = CMPConsentTool(cmpConfig: cmpConfig, viewController: self)
  
/** Initialize without CmpConfig */
  
cmpConsentTool = cmpConsentTool(CMPConsentTool(domain: myCmpConfig.domain, codeId: myCmpConfig.appId, appName: myCmpConfig.appName, language: myCmpConfig.language, viewController: self))
        
/** Optionally chain callbacks */
cmpConsentTool = cmpConsentTool.withOpenListener(onOpen)
            				   .withOnCmpButtonClickedCallback(onButtonClickedEvent)
            				   .withCloseListener(onClose)
           					   .withErrorListener(onCmpError)

Bitte beachten Sie, dass es wichtig ist, das SDK in der viewDidLoad-Methode zu initialisieren. Andernfalls ist die Ansicht möglicherweise nicht einsatzbereit und das SDK schlägt möglicherweise fehl.

Bitte stellen Sie sicher, dass Sie die richtigen Konfigurationsdaten verwenden. Die Konfigurationsdaten finden Sie in Ihrem consentmanager Konto bei Menü > Code abrufen > CodeId

SwiftUI

Um das SDK in eine SwiftUI-Umgebung zu integrieren, müssen Sie eine 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 consentmanager


class CmpViewController: UIViewController {
    struct CmpConfig {
           static let domain = "delivery.consentmanager.net"
           static let appId = "123456"
           static let appName = "test App"
           static let language = "DE"
       }
    var cmpConsentTool: CMPConsentTool? = nil
    func onClose() -> Void {
        NSLog("closed event");
    }

    func onOpen() -> Void {
        NSLog("opened event");
    }

    func onCMPNotOpened() -> Void {
        NSLog("not opened event");
    }
    
    override func viewDidLoad() {
        cmpConsentTool = cmpConsentTool(CMPConsentTool(domain: CmpConfig.domain, codeId: CmpConfig.appId, appName: CmpConfig.appName, language: CmpConfig.language, viewController: self))
        // creating a example button to manually open the consent screen
        let button = UIButton.init(frame: CGRect.init(x: 10, y: 100, width: 100, height: 50))
        button.setTitle("Consent", for: .normal)
        button.backgroundColor = .red
        button.addTarget(self, action: #selector(onShowConsentClicked), for: .touchUpInside)
        self.view.addSubview(button)
    }
    
    /**
     * Show consent button was clicked
     */
    @objc func onShowConsentClicked(sender: UIButton!) {
        cmpConsentTool!.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

Verwenden des SDK

Auf Zustimmung prüfen

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

if(consentTool!.hasPurposeConsent("52", purposeIsV1orV2: false))
{
    if(consentTool!.hasVendorConsent("s26", purposeIsV1orV2: false))
    {
        //do something with data
    }
}

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

cmpConsentTool!.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. Verwenden Sie die folgende Funktion, um die Einwilligungsinformationen vom SDK an die Webansicht zu übertragen:

consentData = CmpConsentTool.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)

Seit iOS 14 hat Apple das Apple Tracking Transparency Framework eingeführt, das verlangt, dass jede App offenlegen muss, welche Tracking-Daten sie verwendet. Das ATT-Framework allein ist nicht mit dem IAB TCF/DSGVO usw. konform und ist nur eine Apple-spezifische Version, um die Zustimmung des Benutzers zum Verfolgen von Daten einzuholen. Um dem Benutzer ein besseres Erlebnis zu ermöglichen, unterstützen wir eine Lösung zur Synchronisierung der Einwilligungen zwischen dem CMP SDK und der ATT-Schnittstelle. Das SDK bietet hierfür zwei unterschiedliche Lösungen an. 

1. Der Entwickler integriert das ATT-Framework selbst und übergibt dann die resultierenden Informationen an das CMP-SDK. Apples Dokumentation kann gefunden werden hier

Wir empfehlen diese Integration. Sie sind weiterhin in der Lage, die volle Kontrolle über die ATT-Oberfläche zu erlangen und Ihren benutzerdefinierten Prozess je nach Benutzer zu implementieren.  

So könnte die Integration aussehen. 

       func requestPermission() {
           if #available(iOS 14, *) {
               ATTrackingManager.requestTrackingAuthorization(completionHandler: { status in
                   switch status {
                   case .authorized:
                       // Tracking authorization dialog was shown and accepted
                       // TODO custom code here:
                   case .denied:
                       // Tracking authorization dialog was shown and permission is denied
                       // TODO custom code here:
                   case .notDetermined:
                       // Tracking authorization dialog has not been shown
                       // TODO custom code here:
                   case .restricted:
                       // Tracking authorization dialog has not been shown app is restricted for tracking
                       // TODO custom code here:
                   }
                   // After determination of the att status, pass the information to the cmp sdk                                                           
                   CmpConfig.setAppleTrackingStatus(status.rawValue);
               })
           }
       }

Die Berechtigungsanfrage könnte so aussehen. Die wichtige Codezeile ist 19, wo die Informationen an das CMP SDK übergeben werden. Abhängig vom ATT-Status setzt das CMP SDK vordefinierte Einwilligungsinformationen. 

2. Der Entwickler aktiviert das automatische Apple-Tracking. Das CMP SDK verarbeitet die Anforderung mit einem Standardprotokoll. Der Status wird dann vom CMP SDK verarbeitet. Danach ist es möglich, den ATT-Status vom Entwickler abzurufen, benutzerdefinierte Aktionen sollten jedoch auf Anfrage wie in Option 1 behandelt werden. Sie können die automatische ATT-Anfrage aktivieren mit:

Dadurch wird die ATT-Schicht des Betriebssystems angezeigt. 

CmpConfig.setAutoAppleTracking(true);

Stellen Sie sicher, dass Sie diese Funktion aktivieren, bevor Sie das CMP SDK instanziieren. 

Wenn Sie ATT nicht verwenden, müssen Sie möglicherweise eine Notiz für die automatische Apple-Überprüfung machen. Da der Apple ATT als Option integriert ist, aber nicht genutzt wird. Apple genehmigt den Antrag möglicherweise nicht automatisch.

Benutzerdefinierte Ereignislistener

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

Zustimmung zum Importieren/Exportieren

Um die Einwilligung zu importieren oder zu exportieren, können Sie die Funktion verwenden exportCMPData() und importCMPData(String cmpData). Überprüfen Sie das folgende Beispiel: 

// Instanstiate CMPConsentTool()
cmpConsentTool = CMPConsentTool.init(...)

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

// ... Your code here ...


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

Der zu übergebende ConsentString sollte base64-codiert sein.

CMP SDK-Sequenzdiagramm

In diesem Beispiel zeigen wir Ihnen drei mögliche SDK-Sequenzflüsse zum Verständnis consentmanager und dort Prozesse. 

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:

Dynamische Inhaltsblockierung mit Platzhalter-UIView

Diese Funktion ist veraltet und wird in Zukunft entfernt. Bitte verwenden Sie die API „enableVendorList“.

Der Platzhalter viewObject kann implementiert werden, um die Funktionalität der dynamischen Inhaltsblockierung zu erhalten hier.Sie können die Ansicht mit der folgenden Methode erstellen: 

class ViewController: UIViewController, CmpPlaceholderAcceptedDelegate {
//...
  
@objc func createPlaceholderView{
	let params : CmpPlaceholderParams = CmpPlaceholderParams.init(vendorId: "123");
	let placeholder : CmpPlaceholderView = (cmpConsentTool?.createPlaceholder(CGRect.init(x: 0, y: 300, width: view.frame.size.width, height: 				view.frame.size.height), params))!;
	placeholder.vendorDelegate = self;
	view.addSubview(placeholder);	
}



func vendorAccepted(_ placeholderView: CmpPlaceholderView!) {
	//... actions to do when the consent is accepted
  	// Like showing youtube video view
}
// ...
}

Mit dem Wrapper-Objekt CMPPlaceholderParams Sie können auch optionale Parameter wie benutzerdefinierte Texte oder ein optionales Vorschaubild übergeben. Sie können benutzerdefinierte Texte wie unten gezeigt hinzufügen: 

params.buttonText = "Click me";

Die erforderliche Geschäftslogik, wenn Sie die Ansicht anzeigen möchten und wenn sie nicht vom Entwickler angewendet werden muss. Um Informationen abzurufen, wenn der Benutzer mit dem Platzhalter interagiert, können Sie den vorbereiteten Delegaten CmpPlaceholderAcceptedDelegate verwenden. Mit dem Delegaten müssen Sie die Funktion "vendorAccepted" implementieren, mit der Sie zusätzliche Logik steuern können, wenn der Benutzer die Zustimmung akzeptiert hat. 

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 „CmpConfig“ 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. Das maximale Niveau beträgt 4.

CmpConfig.setVerboseLevel(4)

• 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.