[Android] 1. consentmanager SDK-Integration
Das consentmanager SDK für Android-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
- Integrieren Sie das SDK in die App und konfigurieren Sie die SDK-Einstellungen
- Sobald das SDK in eine App eingebunden ist, stellt das SDK Funktionen für den App-Entwickler bereit, um Zustimmungsdaten abzurufen
- Sobald die App gestartet wird, ruft das SDK automatisch Informationen von der ab consentmanager Server, um das SDK für die Verwendung vorzubereiten.
- 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. - 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
Seit Version 1.7.0 wurde das SDK-Repository in das offizielle Maven-Repository verschoben. Den Migrationsleitfaden finden Sie hier hier
Finden Sie die kompatiblen nativen SDK-Versionen .
Gradle
Fügen Sie die Abhängigkeit zu build.gradle Ihrer App hinzu. (Um immer die neueste Version zu erhalten, verwenden Sie das +-Symbol, um die neuesten Updates zu erhalten. Sie können beispielsweise immer die neuesten Versionen für kleinere Updates bis 1.x.+ erhalten.)
dependencies {
implementation 'net.consentmanager.sdk:android:x.xx.x'
}
Maven
Fügen Sie die Abhängigkeit zu build.gradle Ihrer App hinzu. (Um immer die neueste Version in Maven zu erhalten, können Sie verschiedene Methoden verwenden, um den Versionsbereich abzulehnen. Sie können sie nachschlagen hier )
<dependency>
<groupId>net.consentmanager.sdk</groupId>
<artifactId>android</artifactId>
<version>x.xx.x</version>
</dependency>
Verwenden der Bibliothek
Berechtigungen
Für dieses SDK sind die folgenden Berechtigungen erforderlich. Stellen Sie sicher, dass Sie diese zu Ihrer AndroidManifest.xml hinzufügen:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
Initiieren Sie ConsentTool
Mit dem App-Start (normalerweise Ihrer viewDidAppear-Funktion) müssen Sie eine Instanz der Klasse CMPConsentTool erstellen. 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.
Um das ConsentTool zu initiieren, wechseln Sie zu Ihrer Zielklasse und erstellen Sie eine Instanz von CMPConsentTool wie unten gezeigt:
class CmpDemoActivity : FragmentActivity() {
private lateinit var cmpManager: CmpManager
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val config = CmpConfig.apply {
id ="yourid"
domain = ConsentActivity.CMP_DOMAIN
appName = ConsentActivity.CMP_APP_NAME
language = ConsentActivity.LANG
}
cmpManager = CmpManager.createInstance(this, config)
cmpManager.initialize(this)
}
// Java example instantiation:
CmpManager cmpManager = null;
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
CmpConfig cmpConfig = CmpConfig.INSTANCE;
cmpConfig.setId("YourId");
cmpConfig.setDomain("delivery.consentmanager.net");
cmpConfig.setAppName("YourAppName");
cmpConfig.setLanguage("EN");
cmpConfig.setTimeout(4000);
cmpManager = CmpManager.createInstance(this, cmpConfig);
}
// ... open layer and asking for purpose:
cmpManager.openConsentLayer(getApplication());
if (cmpManager.hasPurposeConsent("PURPOSE_ID")) {
Log.d(TAG, "has purpose");
}
Um die Instanz von CMPConsentTool zu erstellen, müssen Sie die Instanz konfigurieren. Sie müssen die CODE-ID, die Serverdomäne, einen App-Namen und eine Sprache angeben. Die CODE-ID und die Serverdomäne finden Sie in Ihrem consentmanager Konto unter Menü> Code abrufen. Der App-Name kann verwendet werden, um verschiedene Apps in der zu unterscheiden consentmanager Berichterstattung. Für die Sprache können Sie entweder eine leere Zeichenfolge ("") zur automatischen Erkennung oder einen aus zwei Buchstaben bestehenden Sprachcode ("EN", "DE", "FR" usw.) verwenden.
Die Konfigurationswerte können auf verschiedene Arten eingefügt werden:
a) SDK-Konfiguration über CmpConfig
Fügen Sie Ihrem Code die folgenden Zeilen hinzu:
val config = CmpConfig.apply {
serverDomain = CMP_DOMAIN
appName = CMP_APP_NAME
language = LANG
id = CODE_ID
}
cmpManager = CmpManager.createInstance(this, config)
b) SDK-Konfiguration über createInstance()
Fügen Sie Ihrem Code die folgende Zeile hinzu:
cmpManager =
CmpManager.createInstance(
this,
config.id,
config.domain,
config.appName,
config.language
)
Initialisieren und Öffnen der Zustimmungsebene
Um zu prüfen, ob der Benutzer seine Einwilligung erteilen muss, und um die Einwilligungsebene zu öffnen, gibt es verschiedene Optionen.
Per Initialisierungsaufruf
Das initialize
Die Funktion dient dazu, das CMP SDK in Ihrem Anwendungskontext einzurichten und die Zustimmungsebene bei Bedarf automatisch zu überprüfen und zu öffnen. Der initialize
kann mit der Instanzerstellung verkettet werden
cmpManager = CmpManager.createInstance(this, config).initialize(this)
Per CheckAndOpen-Aufruf
Ähnlich wie die initialize
Die CheckAndOpenLayer-Funktion öffnet bei Bedarf die Zustimmungsschicht.
cmpManager.checkAndOpenConsentLayer(this)
Von Hand
Das check
Die Funktion bietet einen manuellen Ansatz, um festzustellen, ob eine Benutzereinwilligung erforderlich ist. Es ermöglicht einen Rückrufmechanismus und einen optionalen Cache-Mechanismus, um Netzwerkanforderungen zu reduzieren.
cmpManager.check({ isConsentRequired ->
if (isConsentRequired) {
// Consent is required, handle accordingly
runOnUiThread {
// Update UI or show consent dialog
cmpManager.openLayer()
}
} else {
// Consent is not required, proceed with application logic
}
}, isCached = true)
Erstellen eines benutzerdefinierten Layouts
Zum Erstellen eines benutzerdefinierten Layouts können Sie das verwenden CmpUIConfig
Klasse mit verschiedenen Styling-Optionen. Diese Klasse bietet auch einige voreingestellte Layouts wie
- configureHalfScreenBottom
- configureHalfScreenTop
- configureCenterScreen
- configureSmallCenterScreen
- configureLargeTopScreen
- configureLargeBottomScreen
Für die Erstellung eines benutzerdefinierten Layouts bietet das CMP SDK auch verschiedene Strategien an:
- Dialogfenster
- Pop-up-Fenster
- Fragment
Sie können die Strategie ändern, indem Sie den Parameter UIConfig festlegen:
CmpUIConfig.uiStrategy = CmpUIStrategy.DIALOG
CmpUIConfig.uiStrategy = CmpUIStrategy.POPUP
CmpUIConfig.uiStrategy = CmpUIStrategy.ACTIVITY
CmpUIConfig.uiStrategy = CmpUIStrategy.FRAGMENT
Wir empfehlen die Verwendung eines Popup-Fensters, das seit Version 2.3.0 auch als Standard festgelegt ist
Zwei wichtige Parameter bestimmen die Pop-up und Dialog Verhalten:
Popup-Verhalten
Parameter | isFocusable = true | isFocusable = false |
isOutsideTouchable = true | Wird bei Berührung von außen abgewiesen. Kann den Fokus für Eingabeereignisse gewinnen. | Wird bei Berührung von außen abgewiesen. Erhält keinen Fokus und fängt Tastatureingaben nicht ab. |
isOutsideTouchable = false | Lässt sich bei Berührung von außen nicht abweisen. Kann sich konzentrieren und Eingabeereignisse abfangen. | Lässt sich bei Berührung von außen nicht abweisen. Erhält keinen Fokus und fängt Tastatureingaben nicht ab. |
Dialogverhalten
Parameter | isFocusable = true | isFocusable = false |
isOutsideTouchable = true | Wird bei Berührung von außen abgewiesen (setCanceledOnTouchOutside(true) ). Der Dialog ist standardmäßig fokussierbar. |
Der Dialog wird bei Berührungen von außen nicht abgewiesen und verhält sich möglicherweise nicht wie erwartet, da Dialoge normalerweise fokussierbar sind. |
isOutsideTouchable = false | Lässt sich bei Berührung von außen nicht abweisen (setCanceledOnTouchOutside(false) ). Der Dialog bleibt fokussierbar und kann Eingabeereignisse abfangen. |
Der Dialog lehnt Berührungen von außen nicht ab und verhält sich aufgrund mangelnder Fokussierbarkeit möglicherweise nicht wie erwartet. |
Beispiel für Fragment:
R.id.cmpContainer
ist ein Framelayout, das in der Aktivitätslayout-XML in layout/{your_activity}.xml so aussehen könnte<FrameLayout
android:id="@+id/cmpContainer"
android:layout_width="match_parent"
android:layout_height="400dp"
android:translationZ="90dp"
app:layout_constraintTop_toTopOf="parent" />
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 Chrome, 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, beispielsweise das Öffnen einer Android-Aktivität.
// apply the domains to be whitelisted
CmpConfig.apply {
id = cmpId
domain = cmpDomain
appName = cmpAppName
language = cmpLanguage
domainWhitelist = cmpDomainWhitelist
}
// implement the callback: CmpOnClickLinkCallback
override fun onClickLink(url: String): Boolean {
Log.d("CMP", url)
// Business logic
return true // return handleWebViewInteraction boolean
}
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:
cmpManager?.hasPurposeConsent(purposeTextState.value)
cmpManager?.hasVendorConsent(vendorTextState.value)
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 openCmpConsentToolView()
:
cmpManager?.openConsentLayer(context)
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:
String 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);
Benutzerdefinierte Ereignislistener
Um zusätzliche Prozesslogik hinzuzufügen, können Sie Event Listener verwenden. Folgende Ereignis-Listener sind verfügbar:
Name |
Tritt auf
|
OnOpenCallback |
Listener für Ereignis beim Öffnen von CMP |
OnCMPCloseCallback |
Listener für Ereignis, wenn CMP geschlossen ist |
OnCMPNotOpenedCallback |
Listener für Ereignis, wenn CMP nicht geöffnet werden muss |
OnErrorCallback |
Listener für Event, wenn ein Fehler im Consent Management-Prozess auftritt. |
OnButtonClickedCallback |
Listener für ButtonEvent |
Zustimmung zum Importieren/Exportieren
Um die Einwilligung zu importieren oder zu exportieren, können Sie die Funktion verwenden exportCMPData(Kontextkontext) und importCMPData(Kontextkontext, String cmpData). Überprüfen Sie das folgende Beispiel:
// Importing consent data if you like
cmpManager?.importCmpString(
"yourConsentString"
) { _, message ->
coroutineScope.launch {
snackbarHostState.showSnackbar(
message = message,
actionLabel = "Action",
duration = SnackbarDuration.Short
)
}
}
// Exporting Consent data
String consentString = cmpManager.exportCmpString();
Der zu übergebende ConsentString sollte base64-codiert sein.
CMP SDK-Sequenzdiagramm
Protokollierung
Wenn Sie unser Android SDK verwenden, müssen Sie möglicherweise für verschiedene Zwecke Protokollinformationen 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 mit Logcat in Android Studio.
Suchen Sie nach dem Tag: Geben Sie in die Suchleiste über den Protokollanweisungen ein CMP
um die mit „CMP“ gekennzeichneten Protokolle herauszufiltern.
Optional: Aktivieren Sie den Debug-Modus
In CMPConfig
, einstellen isDebugMode = true
.
val config = CmpConfig.apply {
// ... other settings
isDebugMode = true
}
- Ermöglicht detailliertere Protokolle mit dem Tag „CMP“.
- Nützlich zum Debuggen und Analysieren.
Problemlösung
Klasse nicht gefunden oder NoSuchMethodException:
ProGuard kann manchmal Klassennamen verschleiern oder Methoden entfernen, auf die dynamisch über Reflektion verwiesen wird. Um dies zu beheben, müssen Sie mithilfe von die Klassen und Methoden angeben, die in der ProGuard-Konfigurationsdatei intakt bleiben sollen -keep
Richtlinie.
Beispielhafte ProGuard-Konfiguration zum Beibehalten einer bestimmten Klasse und ihrer Methoden:
# Kotlin serialization looks up the generated serializer classes through a function on companion
# objects. The companions are looked up reflectively so we need to explicitly keep these functions.
-keepclasseswithmembers class **.*$Companion {
kotlinx.serialization.KSerializer serializer(...);
}
# If a companion has the serializer function, keep the companion field on the original type so that
# the reflective lookup succeeds.
-if class **.*$Companion {
kotlinx.serialization.KSerializer serializer(...);
}
-keepclassmembers class <1>.<2> {
<1>.<2>$Companion Companion;
}
# If your project uses WebView with JS, uncomment the following
# and specify the fully qualified class name to the JavaScript interface
# class:
-keepclassmembers class * {
@android.webkit.JavascriptInterface <methods>;
}
-keepattributes JavascriptInterface
-keepclassmembers class net.consentmanager.sdk.common.callbacks.* {
public *;
}
-keepclassmembers class net.consentmanager.sdk.consentlayer.ui.consentLayer.CmpWebView {
public *;
}
-keepclassmembers class net.consentmanager.sdk.consentlayer.ui.CmpLayerAppInterface {
public *;
}
-keep class net.consentmanager.sdk.CMPConsentTool {
*;
}
-keepclassmembers class * {
@android.webkit.JavascriptInterface <methods>;
}
-keepattributes JavascriptInterface
# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`.
# If you have any, uncomment and replace classes with those containing named companion objects.
#-keepattributes InnerClasses # Needed for `getDeclaredClasses`.
#-if @kotlinx.serialization.Serializable class
#com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions.
#com.example.myapplication.HasNamedCompanion2
#{
# static **$* *;
#}
#-keepnames class <1>$$serializer { # -keepnames suffices; class is kept when serializer() is kept.
# static <1>$$serializer INSTANCE;
#}