[iOS] 1. consentmanager SDK-integration
Utfasad SDK/uppgradera till v3: Den här dokumentationen beskriver version 2.x av vår SDK. 2.x SDK är utfasad och kommer att tas bort av EOY 2025. Uppgradera till SDK version 3.x. Se hjälpavsnittet om SDK v3 här.
I det här dokumentet hittar du allmän information om hur du integrerar vår SDK i ditt projekt. För ytterligare information, se vår API-referens dokumentation. För vår demo-app som visar användningsfallen och en implementering som kan fungera som utgångspunkt, vänligen kontrollera vår repo.
1. Installation
Smakämnen consentmanager SDK för iOS-appar implementerar och tillhandahåller funktionalitet för att informera användaren om dataskydd och fråga och samla in samtycke från användaren. Det gör det möjligt för app-utvecklare att enkelt integrera consentmanager tjänst i deras app.
Steg - Beskrivning på hög nivå
-
Integration och konfiguration:
- Integrera SDK:n i din app.
- Konfigurera SDK-inställningarna efter dina behov.
-
Skapa en instans:
- Vid appstart skapar du en instans av
CMPManagerklass. Denna instans kommer att hantera samtyckesprocessen.
- Vid appstart skapar du en instans av
-
SDK-initiering:
- När instansen är klar hämtar SDK automatiskt nödvändig information från consentmanager servrar för att förbereda för dess drift.
-
Visar samtyckesskärmen:
- SDK:n visar automatiskt samtyckesskärmen om det behövs när
CMPManagerinstans skapas.
- SDK:n visar automatiskt samtyckesskärmen om det behövs när
-
Behandling av personuppgifter:
- När samtycken har samlats in lagras informationen och är tillgänglig för frågor genom olika egenskaper och metoder som exponeras av vår SDK. Du kommer att ha information om avvisade eller accepterade samtycken, leverantörer, syften etc.
Genom att följa dessa steg säkerställer du att din app är kompatibel med samtyckeskraven och att användarens samtycke hanteras och lagras korrekt.
Consent Manager Leverantörs SDK-sekvensdiagram
För att illustrera stegen ovan, låt oss kolla i diagrammet nedan tre möjliga SDK-sekvensflöden.
1. När du skapar en instans med hjälp av initialisera funktion finns det två möjliga utfall. Den första är när consentmanger API informerar SDK om att CMP inte kommer att öppnas, vilket utlöser OnCmpNotOpenedCallback. Det andra resultatet är när samtyckesskiktet öppnas, så att användaren kan interagera med det, och detta utlöser OnOpenCallback. När användaren ger sitt samtycke och samtycket behandlats, PåCmpCloseCallback kallas.
Observera att Vid feluppringning representeras av de röda streckade pillinjerna för att ge exempel på när fel kan uppstå under processen.
2. Skapa en instans och anropa openAndCheckConsent funktioner kommer att leda till en liknande process. Skillnaden är att genom att frikoppla skapandet av instansen och kontrollen för consentmanger API får du möjligheten att lägga till affärslogik och interagera med bibliotekens API.
3. Skapa en instans och anropa openLayer funktionen öppnar lagret utan att markera consentmanager, om det är nödvändigt. Om det redan finns ett samtycke kommer alternativen och inställningarna att visas för användaren. Processflödet kommer att se ut så här:
För ytterligare information om vår SDK-versionsöversikt och ändringslogg, se denna länk.
Installation via Cocoapod
Du kan installera consentmanager SDK genom att lägga till CmpSdk till din Podfile som förklaras i exemplet nedan:
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
...
endNär detta är klart måste du köra pod install i din projektkatalog för att installera consentmanager SDK. Efter detta, vänligen öppna *.xcworkspace och bygga.
När du har följt alla steg bör ditt beroende installeras och du kan fortsätta och använda det i ditt projekt.
Installation via Swift Package Manager
- Öppna Swift Package Manager.
- Gå till
File>Swift Packages>Add Package Dependency. - Lägg till SDK-arkivets URL
Du kommer nu att se ett nytt fönster där du kan ange URL:en till SDK:s arkiv. De flesta SDK:er finns på GitHub, så webbadressen kommer ofta att se ut som
https://github.com/iubenda/cm-sdk-xcframework.git
När du har angett webbadressen klickar duNext. - Välj SDK-versionen
SPM kommer nu att hämta arkivet och ber dig välja en version.
Du kan välja att lägga till paketet genom att välja en versionsregel:
-Up to Next Major: Detta kommer att uppdatera paketet till nästa större version. Det är det rekommenderade alternativet eftersom det lägger till uppdateringar som inte har brytande ändringar.
-Up to Next Minor: Detta kommer att uppdatera paketet till nästa mindre version.
-Exact: Detta låser paketet till en specifik version. Inga uppdateringar kommer att installeras.
Välj den version du vill använda och klickaNext. - Lägg till SDK till ditt mål
På nästa skärm väljer du de mål som du vill lägga till paketberoendet till. Mål är vanligtvis din app och eventuella tester som du kan ha. KlickFinishför att slutföra processen. - Importera SDK
Nu när SDK:n har lagts till i ditt projekt måste du importera den för att kunna använda den. Gå till filen där du vill använda SDK:n och lägg till följande importsats överst:
import CmpSdk2. Initiera SDK
Inom app-start (din viewDidLoad funktion), måste du skapa en instans av klass CMPManager. De initialize() funktionen hämtar automatiskt nödvändig information från vår server och avgör om samtyckesskärmen måste visas eller inte. Om så är fallet kommer SDK automatiskt att visa samtyckesskärmen vid denna tidpunkt, samla in data och tillhandahålla data till appen. Instansen kan sedan användas för att få samtyckesinformation från SDK:n för att kunna använda den i appen.
Exempel på initiering, med hjälp av det automatiska beteendet hos initialize() metod:
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
}
} SDK erbjuder, för flexibilitetens skull, ett sätt att manuellt visa samtyckeslagret, men till priset av två sidvisningar, en för kontrollmetoden, en annan för openLayer-metoden. Exempel:
// 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
}
}
Observera att det är viktigt att använda initialize() metod i SDK:n i metoden viewDidLoad, om du bestämmer dig för den automatiska initieringen. Annars kanske vyn inte är redo att användas och SDK:n kan misslyckas. Se också till att du använder rätt konfigurationsdata. Konfigurationsdata finns i din consentmanager konto på Meny > CMPs > Hämta kod för appar > Kod-ID
SwiftUI
För att integrera SDK:n i en SwiftUI-miljö måste du tillhandahålla en UIViewController som är insvept i en UIViewControllerRepresentable. Du kan hitta mer information om på tjänstemannen äpple dokumentation. Innan du integrerar SDK:n se till att du redan har integrerat modulen i ditt projekt.
1. Vi börjar med att skapa en vanlig UiViewController liknande exemplen 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. För att använda styrenheten i swiftUI du måste skapa en UIViewControllerRepresentable som instansierar CmpViewController:
import SwiftUI
struct CmpViewControllerRepresentable: UIViewControllerRepresentable {
func makeUIViewController(context: Context) -> UIViewController {
let cmpViewController = CmpViewController()
return cmpViewController
}
func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
}
}
3. Nu kan vi använda ControllerView i SwiftUI-kontexten:
import SwiftUI
@main
struct cmpApp: App {
var body: some Scene {
WindowGroup {
CmpViewControllerRepresentable()
}
}
}
3. Använda SDK
Kontrollerar samtycke
För att kontrollera om en leverantör eller syfte har samtycke kan du använda de två metoderna:
if cmpManager!.hasPurposeConsent("52")
{
if cmpManager!.hasVendorConsent("s26")
{
//Add your logic here
}
}Båda metoderna hasPurposeConsent och hasVendorConsent kräver två parametrar:
- id - Sträng av leverantören eller syfte-ID. Observera att leverantörs-ID: n kan ha olika format ("123", "s123" och "c123"), vänligen dubbelkontrollera med Meny> Leverantörer och Meny> Syften i din consentmanager konto.
- isIABVendor / isIABPurpose - Om leverantören eller syftet är en leverantör / syfte som följer IAB TCF-standarden, måste du ställa in en sann, annars en falsk.
Kom ihåg: Alla leverantörer som inte tillhör IAB har ID som börjar med "s" eller "c" (t.ex. "s123"); leverantörer som tillhör IAB har ID som inte börjar med "s" eller "c".
Öppna åtkomstskärmen igen
För att låta användaren ändra valen kan du helt enkelt ringa openView()
cmpManager!.openView()Överlåta samtyckeinformation till andra källor
I vissa fall kan en inbyggd app innehålla webbvisningar för att visa vissa saker som reklam eller innehåll. För att överföra samtyckesinformationen från SDK till webbvyn, använd funktionen:
consentData = cmpManager.exportCmpString();Detta kommer att exportera samtyckeinformationen och all ytterligare information som behövs av CMP. Du kan sedan skicka den här informationen till CMP som finns i din webbvy genom att lägga till den i URL: en som heter i webbvisningen:
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 med Apple Tracking Transparency (ATT)
Om du använder spårning eller analys i din app rekommenderar vi att du läser guiden på ATT-implementering här.
Skapa en anpassad layout
För en anpassad layout finns det 2 callback-funktioner som tillhandahåller viewController och uiView. I exemplet nedan kan du se hur du anpassar layouten:
let cmpLayout = CmpLayout.default()
cmpLayout?.cornerRadius = 10.0
cmpLayout?.customLayout = CGRect(x: 0, y: 0, width: 200, height: 300)
cmpManager = CMPManager(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. med CmpViewControllerConfigurationBlock
Den här funktionen låter dig anpassa vykontrollerns presentationsstil för SDK:ns komponent. Genom att skicka ett konfigurationsblock kan du ändra olika egenskaper för vykontrollern, till exempel dess modala presentationsstil.
Exempelvis:
.withCmpViewControllerConfigurationBlock({ viewController in
// Ensure the viewController is not nil before applying the configuration
viewController?.modalPresentationStyle = .currentContext
})2. med CmpViewConfigurationBlock
Med den här funktionen kan du anpassa UI-vyn för SDK:ns komponent. Genom att skicka ett konfigurationsblock kan du ändra olika egenskaper för vyn, såsom dess layout och utseende
Exempelvis:
.withCmpViewConfigurationBlock({ uiView in
// Configure the uiView to display as a half-screen top layout
CmpUIConfig.configureHalfScreenTop(for: uiView)
})Anpassade evenemangslyssnare
För att lägga till ytterligare processlogik kan du använda dig av Event Listeners. Följande evenemangslyssnare är tillgängliga:
| Namn |
Förekommer
|
|
CmpOpenListener |
Lyssnare efter händelse när CMP öppnas |
|
CmpCloseListener |
Lyssnare för händelse när CMP är stängt |
|
CmpNotOpenedListener |
Lyssnare för Event när CMP inte behöver öppnas |
|
CmpErrorListener |
Lyssnaren kommer att anropas om ett fel uppstår när servern anropas eller vyn visas. |
|
CmpButtonClickedListener |
Lyssnare för händelse när knappen klickas och samtyckeslagret stängs |
|
CmpATtrackingStatusChangedListener |
Lyssnare för ATTracking Status ändrad |
|
onCmpUpdateGoogleConsent |
Lyssnare för ändringar i samtyckesläge |
Import/Export samtycke
För att importera eller exportera samtycket kan du använda funktionerna exportCMPString() och importCMPString(). Kontrollera exemplet nedan:
// Importing consent data if you like
cmpManager.importCmpString("${your base64 encoded consentString}");
// ... Your code here ...
// Exporting Consent data
let consentString : String = cmpManager.exportCmpString()ConsentString ska vara base64-kodad.
Interna applänkar och domänvitlista
För att implementera funktionen där vissa domäner är vitlistade och, när de nås inom samtyckesplattformen (CMP) WebView, inte öppnas i en extern webbläsare som Safari utan inom själva WebView, kan du implementera en återuppringningsmekanism för att utföra anpassade åtgärder baserat på domän, som att öppna en annan 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
}) Loggning
För att implementera funktionen där vissa domäner är vitlistade och, när de nås inom samtyckesplattformen (CMP) WebView, inte öppnas i en extern webbläsare som Safari utan inom själva WebView, kan du implementera en återuppringningsmekanism för att utföra anpassade åtgärder baserat på domän, som att öppna en annan ViewController:
Interna applänkar och domänvitlista
För att implementera funktionen där vissa domäner är vitlistade och, när de nås inom samtyckesplattformen (CMP) WebView, inte öppnas i en extern webbläsare som Safari utan inom själva WebView, kan du implementera en återuppringningsmekanism för att utföra anpassade åtgärder baserat på domän, som att öppna en annan ViewController:
När du använder vår iOS SDK kan du behöva felsöka eller analysera logginformation för olika ändamål. Loggarna som genereras av vår SDK är taggade under "Cmp:", så att du enkelt kan filtrera och bara visa relevanta loggar. Den här guiden ger steg-för-steg-instruktioner om hur du kommer åt dessa loggar i Xcode.
Sök efter taggen
I Xcodes felsökningskonsol kan du söka efter loggar specifikt taggade med "Consent" eller "CMP" för att isolera loggarna som genereras av vår SDK.
Valfritt: Justera Verbose Level
In CmpConfig, kan du justera den utförliga nivån för mer detaljerade loggar.
cmpConfig.isDebugMode = true
cmpConfig.logLevel = CmpLogLevel.debug- Aktiverar mer detaljerade loggar
- Användbar för felsökning och analys.
Genom att justera den utförliga nivån kan du få mer omfattande logginformation, vilket underlättar felsökning och analys av vår SDK:s beteende i din applikation.
