[iOS] 1. consentmanager SDK-integratie

In dit document vindt u algemene informatie over hoe u onze SDK in uw project kunt integreren. Voor meer details verwijzen wij u naar onze API-referentie documentatie. 

1. Installatie

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

Stappen - Beschrijving op hoog niveau

Door deze stappen te volgen, zorgt u ervoor dat uw app voldoet aan de toestemmingsvereisten en dat de toestemming van gebruikers op de juiste manier wordt beheerd en opgeslagen.

Consent Manager Provider SDK-sequentiediagram

Laten we, ter illustratie van de bovenstaande stappen, in het onderstaande diagram drie mogelijke SDK-reeksstromen bekijken. 

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:

Voor meer informatie over ons SDK-versieoverzicht en changelog verwijzen wij u naar deze link.

Installatie via 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.
2. Ga naar File > Swift Packages > Add Package Dependency.
3. Voeg de URL van de SDK-opslagplaats 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
   Nadat u de URL heeft ingevoerd, klikt u op Next.
4. 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.
5. 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.
6. 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

2. Initialiseren van de SDK

Binnen de app-start (uw viewDidLoad function), moet u een instantie van klasse maken CMPConsentTool. De initialize() functie haalt automatisch de benodigde gegevens op van onze server en bepaalt of het toestemmingsscherm getoond moet worden of niet. Als dit het geval is, toont de SDK op dit punt automatisch het toestemmingsscherm, verzamelt de gegevens en verstrekt deze aan de app. De instantie kan vervolgens worden gebruikt om toestemmingsgegevens van de SDK te verkrijgen, zodat deze in de app kunnen worden gebruikt.

Voorbeeld van initialisatie, waarbij gebruik wordt gemaakt van het automatische gedrag van de initialize() methode:

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

De SDK biedt, omwille van de flexibiliteit, een manier om de toestemmingslaag handmatig weer te geven, hoewel dit ten koste gaat van twee paginaweergaven, één voor de check-methode en één voor de openLayer-methode. Voorbeeld: 

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

Houd er rekening mee dat het van essentieel belang is om gebruik te maken van de initialize() methode in de SDK in de viewDidLoad-methode, als u kiest voor automatische initialisatie. Anders is de weergave mogelijk niet gereed voor gebruik en mislukt de SDK mogelijk. Zorg er ook voor dat u de juiste configuratiegegevens gebruikt. De configuratiegegevens vindt u in uw consentmanager account bij Menu > CMP's > Code voor apps ophalen > Code-ID

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

3. De SDK gebruiken

Controle op toestemming

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

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

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

cmpManager!.openView()

Toestemmingsinformatie doorgeven aan andere bronnen

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

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

Als u tracking of analytics in uw app gebruikt, raden we u aan de handleiding te lezen ATT-implementatie hier.

Een aangepaste lay-out maken

Voor een aangepaste lay-out zijn er 2 callback-functies die de viewController en de uiView bieden. In het onderstaande voorbeeld ziet u hoe u de lay-out kunt aanpassen:

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

Met deze functie kunt u de presentatiestijl van de weergavecontroller voor de SDK-component aanpassen. Door een configuratieblok door te geven, kunt u verschillende eigenschappen van de viewcontroller wijzigen, zoals de modale presentatiestijl.

Voorbeeld: 

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

2. metCmpViewConfigurationBlock

Met deze functie kunt u de UI-weergave voor de SDK-component aanpassen. Door een configuratieblok door te geven, kunt u verschillende eigenschappen van de weergave wijzigen, zoals de lay-out en het uiterlijk

Voorbeeld:

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

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 functies gebruiken exportCMPString() en importCMPString(). Check het voorbeeld hieronder: 

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

// ... Your code here ...

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

De toestemmingsstring moet base64-gecodeerd zijn.

Interne app-links en witte lijst met domeinen

Om de functionaliteit te implementeren waarbij bepaalde domeinen op de witte lijst staan ​​en, wanneer ze worden geopend binnen het toestemmingsplatform (CMP) WebView, niet worden geopend in een externe browser zoals Safari maar binnen de WebView zelf, kunt u een callback-mechanisme implementeren om aangepaste acties uit te voeren op basis van de domein, zoals het openen van een andere ViewController:

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

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 "Cmp:", 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.

cmpConfig.isDebugMode = true   
cmpConfig.logLevel = CmpLogLevel.debug

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