[Android] 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 med ett Java- och ett Kotlin-exempel.
Sedan version 1.7.0 har vårt SDK-förråd flyttats till det officiella Maven-förrådet. Migrationsguiden finns här. Hitta de kompatibla inbyggda SDK-versionerna här.
1. Installation
Smakämnen consentmanager SDK för Android-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 - 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
CMPConsentToolklass. 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
CMPConsentToolinstans 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.
Lägger till beroende via Gradle
Lägg till beroendet till dina appar build.gradle. (För att alltid få den senaste versionen använd +-symbolen för att få de senaste uppdateringarna. Du kan till exempel alltid få de senaste versionerna för mindre uppdateringar genom 1.x.+)
dependencies {
implementation 'net.consentmanager.sdk:android:x.xx.x'
}
I
Lägger till beroende via Maven
Lägg till beroendet till dina appar build.gradle. För att alltid få den senaste versionen i maven kan du använda olika metoder för att avböja versionsintervallet. Kontrollera de tillgängliga versionerna av SDK:n denna länk. För ytterligare information, se här.
<dependency>
<groupId>net.consentmanager.sdk</groupId>
<artifactId>android</artifactId>
<version>x.xx.x</version>
</dependency>2. Initiera SDK
behörigheter
Denna SDK kräver följande behörigheter, se till att lägga till dem i din AndroidManifest.xml:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />Initiera samtyckesverktyget - automatiskt
Inom app-start (vanligtvis den vanliga override onCreate() function), måste du skapa en instans av klass CMPConsentTool. 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. Förekomsten 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:
För att initiera ConsentTool, gå till din målgrupp och skapa en instans av CMPConsentTool som visas nedan:
// Kotlin example of initialization of the consent layer
class CmpDemoActivity : FragmentActivity() {
private lateinit var cmpManager: CmpManager
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val config = CmpConfig.apply {
id = "<YOUR-CONSENTMANAGER-APP-ID>" // example: b238acdf1a
domain = "<YOUR-CONSENTMANAGER-APP-DOMAIN>" // example: delivery.consentmanager.net
appName = "<YOUR-CONSENTMANAGER-APP-NAME>" // example: testApp
language = "<YOUR-CONSENTMANAGER-APP-LANGUAGE>" // example: DE
}
cmpManager = CmpManager.createInstance(this, config)
cmpManager.initialize(this)
}
}
// Java example of initialization of the consent layer
public class CmpDemoActivity extends AppCompatActivity {
private CmpManager cmpManager;
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
CmpConfig cmpConfig = CmpConfig.INSTANCE;
cmpConfig.setId("<YOUR-CONSENTMANAGER-APP-ID>"); // example: a000aaaa1a
cmpConfig.setDomain("<YOUR-CONSENTMANAGER-APP-DOMAIN>"); // example: delivery.consentmanager.net
cmpConfig.setAppName("<YOUR-CONSENTMANAGER-APP-NAME>"); // example: testApp
cmpConfig.setLanguage("<YOUR-CONSENTMANAGER-APP-LANGUAGE>"); // example: EN
cmpConfig.setTimeout(4000);
cmpManager = CmpManager.createInstance(this, cmpConfig);
cmpManager.initialize(this)
}
}
För att skapa instansen av CMPConsentTool måste du konfigurera instansen. Du måste ange CODE-ID, serverdomän, ett appnamn och ett språk. KOD-ID och serverdomän finns i din consentmanager konto under Meny> Hämta kod. Appnamnet kan användas för att distribuera olika appar i consentmanager rapportering. För språket kan du antingen använda en tom sträng ("") för automatisk upptäckt eller en två-bokstavs språkkod ("EN", "DE", "FR" och så vidare).
Initiera samtyckesverktyget - manuellt
SDK erbjuder, för flexibilitetens skull, ett sätt att manuellt visa samtyckeslagret, men med kostnaden för två sidvisningar. 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 openConsentLayer(), *
// * so be aware. *
// ***********************************************************************
cmpManager.check({ isConsentRequired ->
if (isConsentRequired) {
// Consent is required, handle accordingly
runOnUiThread {
// Update UI or show consent dialog
cmpManager.openConsentLayer()
}
} else {
// Consent is not required, proceed with application logic
}
}, isCached = true)
Skapa en anpassad layout
För att skapa en anpassad layout kan du använda CmpUIConfig klass med olika stylingalternativ. Den här klassen erbjuder också vissa förinställda layouter som
- konfigurera HalfScreenBottom
- konfigurera HalfScreenTop
- konfigureraCenterScreen
- konfigureraSmallCenterScreen
- configureLargeTopScreen
- configureLargeBottomScreen
För att skapa en anpassad layout erbjuder CMP SDK också olika strategier:
- Dialogfönster
- Pop-up fönster
- fragment
Du kan ändra strategin genom att ställa in UIConfig-parametern:
CmpUIConfig.uiStrategy = CmpUIStrategy.DIALOG
CmpUIConfig.uiStrategy = CmpUIStrategy.POPUP
CmpUIConfig.uiStrategy = CmpUIStrategy.ACTIVITY
CmpUIConfig.uiStrategy = CmpUIStrategy.FRAGMENTVi rekommenderar att du använder ett popup-fönster som också är inställt som standard sedan version 2.3.0
Två viktiga parametrar kommer att avgöra Popup och dialog beteende. I tabellen nedan kan du kontrollera relationen mellan parametrarna isFocusable och isOutsideTouchable:
Popup-beteende
| Parameter | isFocusable = true |
isFocusable = false |
isOutsideTouchable = true |
Avvisar vid yttre beröring. Kan få fokus för input-händelser. | Avvisar vid yttre beröring. Får inte fokus eller fångar tangentbordsinmatning. |
isOutsideTouchable = false |
Avvisar inte vid yttre beröring. Kan få fokus och fånga upp ingångshändelser. | Avvisar inte vid yttre beröring. Får inte fokus eller fångar tangentbordsinmatning. |
Dialogbeteende
| Parameter | isFocusable = true |
isFocusable = false |
isOutsideTouchable = true |
Avvisar vid yttre beröring (setCanceledOnTouchOutside(true)). Dialogrutan är fokuserbar som standard. |
Dialogen avvisar inte vid beröring utifrån och kanske inte beter sig som förväntat eftersom dialoger vanligtvis kan fokuseras. |
isOutsideTouchable = false |
Avvisar inte vid yttre beröring (setCanceledOnTouchOutside(false)). Dialogen förblir fokuserbar och kan fånga upp ingångshändelser. |
Dialog avvisar inte vid beröring utifrån och kanske inte beter sig som förväntat på grund av bristen på fokusbarhet. |
Använder strategin Fragment
R.id.cmpContainer är en ramlayout som kan se ut så här i aktivitetslayouten xml i layout/{din_aktivitet}.xml<FrameLayout
android:id="@+id/cmpContainer"
android:layout_width="match_parent"
android:layout_height="400dp"
android:translationZ="90dp"
app:layout_constraintTop_toTopOf="parent" />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 har två parametrar, en kräver och en valfri:
-
id- Sträng för leverantören eller ändamåls-ID. Observera att leverantörs-ID kan ha olika format ("123", "s123" och "c123"), dubbelkolla med Meny> Leverantörer och Meny> Syften i din consentmanager konto. -
isIABVendor/isIABPurpose(Valfritt) – Om leverantören eller syftet är en leverantör/ändamål som följer IAB TCF-standarden, måste du ange ett sant, annars ett falskt.
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 openConsentLayer():
cmpManager?.openConsentLayer(context)Ö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:
String consentData = cmpConsentTool?.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);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
|
| OnOpenCallback |
Lyssnare efter händelse när CMP öppnade |
| PåCMPCloseCallback |
Lyssnare för händelse när CMP är stängt |
| OnCPMNotOpenedCallback |
Lyssnare för Event när CMP inte behöver öppnas |
|
Vid feluppringning |
Lyssnare för händelse när det finns ett fel i samtyckeshanteringsprocessen. |
| OnButtonClickedCallback |
Lyssnare för ButtonEvent |
Import/Export samtycke
För att importera eller exportera samtycket kan du använda funktionerna exportCMPData() och importCMPData(). Kontrollera exemplet nedan:
// Importing consent data if desired
cmpManager.importCmpString("your_base64_encoded_consentString")
// ... Your code here ...
// Exporting consent data
val consentString: String = cmpManager.exportCmpString()
ConsentString du behöver skicka bör 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 Chrome 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 Android-aktivitet.
// 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
}Loggning
När du använder vår Android SDK kan du behöva felsöka eller analysera logginformation för olika ändamål. Loggarna som genereras av vår SDK är taggade med "CMP", vilket gör 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 med Logcat i Android Studio.
Sök efter taggen: I sökfältet ovanför loggsatserna skriver du CMP för att filtrera bort loggarna taggade med "CMP".
Valfritt: Aktivera felsökningsläge
In CMPConfig, uppsättning isDebugMode = true.
val config = CmpConfig.apply {
// ... other settings
isDebugMode = true
}
- Aktiverar mer detaljerade loggar taggade med "CMP".
- Användbar för felsökning och analys.
Felsökning
Class Not Found eller NoSuchMethodException:
ProGuard kan ibland fördunkla klassnamn eller ta bort metoder som refereras dynamiskt via reflektion. För att fixa detta måste du ange klasserna och metoderna som ska hållas intakta i ProGuard-konfigurationsfilen med -keep Direktiv.
Exempel på ProGuard-konfiguration för att behålla en specifik klass och dess metoder:
# 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;
#}
