[iOS] 1. consentmanager SDK-integratie

Het consentmanager SDK voor iOS-apps implementeert en biedt functionaliteit om de gebruiker te informeren over gegevensbescherming en om toestemming van de gebruiker te vragen en te verzamelen. Het stelt app-ontwikkelaars in staat de consentmanager service in hun app.

Hoe het werkt

1. Integreer de SDK in de app en configureer de SDK-instellingen
2. Zodra de SDK is geïntegreerd in een app, biedt de SDK functies voor de app-ontwikkelaar om toestemmingsgegevens op te halen
3. Zodra de app start, haalt de SDK automatisch informatie op van de consentmanager servers om de SDK voor te bereiden op het gebruik ervan.
4. Het wordt aanbevolen dat de app bij het opstarten van de app een klasse-instantie maakt CMPConsentTool. Zodra dit is gemaakt, toont de SDK indien nodig automatisch het toestemmingsscherm.
5. Wanneer de app persoonlijke gegevens wil verwerken, moet deze de SDK "vragen" of toestemming is gegeven voor het specifieke doel en de leverancier.

Installatie via Cocoapod

Voeg bibliotheek toe met Cocoapod

U kunt de consentmanager SDK door toe te voegen CmpSdk naar uw Podfile zoals uitgelegd in het onderstaande voorbeeld:

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

Zodra dit is gebeurd, moet u rennen pod install in uw projectmap om het consentmanager SDK. Open hierna het *.xcworkspace en bouwen. 

Nadat u alle stappen hebt gevolgd, moet uw afhankelijkheid zijn geïnstalleerd en kunt u doorgaan en deze in uw project gebruiken.

Installatie via Swift Package Manager

1. Open Swift-pakketbeheer

Ga naar File > Swift Packages > Add Package Dependency.

2. Voeg de URL van de SDK-repository toe

U ziet nu een nieuw venster waarin u de URL van de opslagplaats van de SDK kunt invoeren. De meeste SDK's worden gehost op GitHub, dus de URL ziet er vaak zo uit https://github.com/iubenda/cm-sdk-xcframework.git. Klik na het invoeren van de URL op Next.

3. Selecteer de SDK-versie

SPM haalt nu de repository op en vraagt ​​u een versie te selecteren.

U kunt ervoor kiezen om het pakket toe te voegen door een versieregel te selecteren:

• Up to Next Major: Hiermee wordt het pakket bijgewerkt naar de volgende hoofdversie. Het is de aanbevolen optie omdat het updates toevoegt die geen belangrijke wijzigingen hebben.
• Up to Next Minor: Hiermee wordt het pakket bijgewerkt naar de volgende secundaire versie.
• Exact: Hiermee vergrendelt u het pakket op een specifieke versie. Er worden geen updates geïnstalleerd.

Selecteer de versie die u wilt gebruiken en klik Next.

4. Voeg de SDK toe aan uw doel

Selecteer op het volgende scherm de doelen waaraan u de pakketafhankelijkheid wilt toevoegen. Doelen zijn meestal uw app en eventuele tests die u heeft.
Klik Finish om het proces te voltooien.

5. Importeer de SDK 

Nu de SDK aan uw project is toegevoegd, moet u deze importeren om hem te gebruiken. Ga naar het bestand waarin u de SDK wilt gebruiken en voeg bovenaan de volgende importverklaring toe:

import CmpSdk

Start de SDK

Met de app-start (meestal uw viewDidLoad-functie) kunt u Dan moet je maak een instantie van klasse CMPConsentTool. Dit haalt automatisch de benodigde gegevens van onze server op en bepaalt of het toestemmingsscherm moet worden weergegeven of niet. Als dat het geval is, toont de SDK op dit punt automatisch het toestemmingsscherm, verzamelt de gegevens en verstrekt de gegevens aan de app. De instantie kan vervolgens worden gebruikt om toestemmingsgegevens van de SDK op te halen om deze in de app te gebruiken.

/** 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)

Houd er rekening mee dat het belangrijk is om de SDK te initialiseren in de viewDidLoad-methode. Anders is de weergave mogelijk niet klaar voor gebruik en kan de SDK mislukken.

Zorg ervoor dat u de juiste configuratiegegevens gebruikt. De configuratiegegevens vindt u in uw consentmanager account bij Menu > Code ophalen > CodeId

SwiftUI

Om de SDK in een SwiftUI-omgeving te integreren, moet u een: UIViewController die is verpakt in een UIViewControllerVertegenwoordigbaar. U kunt meer informatie vinden over op de officiële Apple-documentatie. Voordat u de SDK integreert, moet u ervoor zorgen dat u de module al in uw project hebt geïntegreerd. 

1. We beginnen met het maken van een gebruikelijke UiViewController vergelijkbaar met de voorbeelden voor 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. Om de controller te gebruiken in de snelleUI je moet een UIViewControllerRepresentable maken die de CmpViewController:

import SwiftUI

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

3. Nu kunnen we de . gebruiken ControllerBekijken binnen de SwiftUI-context:

import SwiftUI

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

Er wordt een voorbeeldproject gegeven hier

De SDK gebruiken

Controleer op toestemming

Om te controleren of een leverancier of doel toestemming heeft, kunt u de twee methoden gebruiken:

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

Beide methoden hasPurposeConsent en hasVendorConsent vereisen twee parameters:

• id - String van de leverancier of het doel-ID. Houd er rekening mee dat leveranciers-ID's verschillende formaten kunnen hebben ("123", "s123" en "c123"), controleer dit nogmaals met Menu> Leveranciers en Menu> Doeleinden in consentmanager account.
• isIABVendor / isIABPurpose - Als de leverancier of het doel een leverancier / doel is die de IAB TCF-standaard volgt, moet u een true instellen, anders een false.

Onthoud: alle leveranciers die niet tot de IAB behoren, hebben ID's die beginnen met een "s" of "c" (bijv. "S123"); leveranciers die tot de IAB behoren, hebben ID's die niet beginnen met een "s" of "c".

Het toestemmingsscherm opnieuw openen

Om de gebruiker in staat te stellen de keuzes te wijzigen, kunt u gewoon bellen openView()

cmpConsentTool!.openView()

Toestemmingsinformatie doorgeven aan andere bronnen

In sommige gevallen kan een systeemeigen app webviews bevatten om bepaalde zaken, zoals advertenties of inhoud van advertenties, weer te geven. Gebruik de functie om de toestemmingsinformatie van de SDK naar de webview te verzenden:

consentData = CmpConsentTool.exportCmpString();

Dit exporteert de toestemmingsinformatie en alle verdere gegevens die de CMP nodig heeft. Vervolgens kunt u deze informatie doorgeven aan de CMP in uw webview door deze toe te voegen aan de URL die wordt opgeroepen in de webview:

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");

Integratie met Apple Tracking Transparency (ATT)

Sinds iOS 14 introduceerde Apple het Apple Tracking Transparency-framework, dat vereist dat elke app openbaar moet maken welke trackinggegevens hij gebruikt. Het ATT-framework op zichzelf is niet compatibel met de IAB TCF/GDPR, enz. en is slechts een Apple-specifieke versie voor het vragen van toestemming van de gebruiker voor het bijhouden van gegevens. Om de gebruiker een betere ervaring te bieden, ondersteunen we een oplossing om de toestemmingen tussen de CMP SDK en de ATT-interface te synchroniseren. De SDK biedt hiervoor twee verschillende oplossingen. 

1. De ontwikkelaar integreert het ATT Framework zelf en geeft de resulterende informatie door aan de CMP SDK. Apples-documentatie is te vinden hier

We raden deze integratie aan. U kunt nog steeds de volledige controle krijgen over de ATT-interface en uw aangepaste proces implementeren, afhankelijk van de gebruiker.  

De integratie zou er zo uit kunnen zien. 

       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);
               })
           }
       }

Het toestemmingsverzoek kan er als volgt uitzien. De belangrijke regel code is 19 waar de informatie wordt doorgegeven aan de CMP SDK. Afhankelijk van de ATT-status stelt de CMP SDK vooraf gedefinieerde toestemmingsinformatie in. 

2. De ontwikkelaar activeert de automatische Apple-tracking. De CMP SDK verwerkt de aanvraag met een standaardprotocol. De status wordt dan afgehandeld door de CMP SDK. Daarna is het mogelijk om de ATT-status door de ontwikkelaar te krijgen. Aangepaste acties moeten echter op verzoek worden afgehandeld zoals in optie 1. U kunt het automatische ATT-verzoek activeren met:

Dit toont de ATT-laag van het besturingssysteem. 

CmpConfig.setAutoAppleTracking(true);

Zorg ervoor dat u deze functie activeert voordat u de CMP SDK start. 

Als u ATT niet gebruikt, moet u mogelijk een notitie maken voor de automatische Apple Review. Omdat de Apple ATT als optie is geïntegreerd, maar niet wordt gebruikt. Het is mogelijk dat Apple de Applicatie niet automatisch goedkeurt.

Aangepaste gebeurtenisluisteraars

Om extra proceslogica toe te voegen kunt u gebruik maken van Event Listeners. De volgende gebeurtenisluisteraars zijn beschikbaar:

Toestemming voor importeren/exporteren

Om de toestemming te importeren of exporteren, kunt u de functie gebruiken: exportCMPData() en importCMPData(String cmpData). Check het voorbeeld hieronder: 

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

De consentString die u moet doorgeven, moet base64-gecodeerd zijn.

CMP SDK-volgordediagram

In dit voorbeeld laten we u drie mogelijke SDK-reeksstromen zien om de consentmanager en daar processen. 

1. Bij het maken van een instantie met behulp van de initialiseren functioneren, zijn er twee mogelijke uitkomsten. De eerste is wanneer de toestemmingsmanager-API de SDK informeert dat de CMP niet kan worden geopend, waardoor de OnCmpNotOpenedCallback. Het tweede resultaat is wanneer de toestemmingslaag wordt geopend, waardoor de gebruiker ermee kan communiceren, en dit activeert de AanOpenTerugbellen. Zodra de gebruiker toestemming geeft en de toestemming is verwerkt, wordt de OnCmpCloseCallback wordt genoemd.

Houdt u er rekening mee dat de OnErrorTerugbellen wordt weergegeven door de rode onderbroken pijllijnen om voorbeelden te geven van wanneer fouten kunnen optreden tijdens het proces.

2. Een instantie maken en de openAndCheckConsent functies zullen tot een soortgelijk proces leiden. Het verschil is dat door het aanmaken van het exemplaar en de controle op de toestemmingsmanger-API te ontkoppelen, u de mogelijkheid krijgt om bedrijfslogica toe te voegen en te communiceren met de bibliotheken-API.

3. Een instantie maken en de openlaag functie opent de laag zonder de consentmanager, als het nodig is. Als er al toestemming is gegeven, worden de opties en instellingen aan de gebruiker getoond. Het procesverloop ziet er als volgt uit:

Dynamische inhoudsblokkering met tijdelijke aanduiding UIView

Deze functie is verouderd en zal in de toekomst worden verwijderd. Gebruik de enableVendorList API

De tijdelijke aanduiding viewObject kan worden geïmplementeerd om de functionaliteit van dynamische inhoudsblokkering te krijgen hierU kunt de weergave op de volgende manier maken: 

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
}
// ...
}

Met het Wrapper-object CMPPlaceholderParams u kunt ook optionele parameters doorgeven, zoals aangepaste teksten of een optionele voorbeeldafbeelding. u kunt aangepaste teksten toevoegen zoals hieronder getoond: 

params.buttonText = "Click me";

De benodigde bedrijfslogica, wanneer u de weergave wilt tonen en wanneer deze niet door de ontwikkelaar hoeft te worden toegepast. Om informatie te krijgen wanneer de gebruiker interactie heeft met de tijdelijke aanduiding, kunt u de voorbereide gemachtigde CmpPlaceholderAcceptedDelegate gebruiken. Met de gemachtigde moet u de functie vendorAccepted implementeren, waarmee u extra logica kunt beheren wanneer de gebruiker de toestemming heeft geaccepteerd. 

Logging

Wanneer u onze iOS SDK gebruikt, kan het nodig zijn om loggegevens voor verschillende doeleinden te debuggen of te analyseren. De door onze SDK gegenereerde logboeken zijn getagd onder "CmpConfig", zodat u eenvoudig alleen de relevante logboeken kunt filteren en bekijken. Deze handleiding biedt stapsgewijze instructies voor het openen van deze logboeken in Xcode.

Zoek naar het label

In de foutopsporingsconsole van Xcode kunt u zoeken naar logboeken die specifiek zijn getagd met 'Toestemming' of 'CMP' om de logboeken te isoleren die door onze SDK zijn gegenereerd.

Optioneel: Pas het uitgebreide niveau aan

In CmpConfig, kunt u het uitgebreide niveau aanpassen voor meer gedetailleerde logboeken. Het maximale niveau is 4.

CmpConfig.setVerboseLevel(4)

• Maakt gedetailleerdere logboeken mogelijk
• Handig voor foutopsporing en analyse.

Door het uitgebreide niveau aan te passen, kunt u uitgebreidere logboekinformatie verkrijgen, wat helpt bij het opsporen van fouten en het analyseren van het gedrag van onze SDK in uw toepassing.