[Android] 1. consentmanager SDK-integratie
We hebben onze SDK bijgewerkt. Gebruik alstublieft SDK v3: https://help.consentmanager.net/books/cmp/page/android-1-consentmanager-sdk-integration-398
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. Voor onze demo-app die de use cases en een implementatie laat zien die als startpunt kan dienen, kijk dan op onze repo met een Java- en een Kotlin-voorbeeld.
Sinds versie 1.7.0 is onze SDK-repository verplaatst naar de officiële Maven-repository. De migratiegids is te vinden hier. Vind de compatibele native SDK-versies hier.
1. Installatie
De consentmanager SDK voor Android-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 - Hoog niveau
-
-
Integratie en configuratie:
- Integreer de SDK in uw app.
- Configureer de SDK-instellingen volgens uw behoeften.
-
Een exemplaar maken:
- Maak bij het opstarten van de app een exemplaar van het
CMPConsentToolklas. Deze instantie zal het toestemmingsproces afhandelen.
- Maak bij het opstarten van de app een exemplaar van het
-
SDK-initialisatie:
- Zodra het exemplaar gereed is, haalt de SDK automatisch de benodigde informatie op uit de consentmanager servers ter voorbereiding op de werking ervan.
-
Het toestemmingsscherm weergeven:
- De SDK geeft indien nodig automatisch het toestemmingsscherm weer wanneer de
CMPConsentToolexemplaar is gemaakt.
- De SDK geeft indien nodig automatisch het toestemmingsscherm weer wanneer de
-
Verwerking van persoonlijke gegevens:
- Zodra de toestemmingen zijn verzameld, wordt de informatie opgeslagen en kan deze worden opgevraagd via verschillende eigenschappen en methoden die door onze SDK worden vrijgegeven. U beschikt over informatie over geweigerde of geaccepteerde toestemmingen, leveranciers, doeleinden, enz.
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.
Afhankelijkheid toevoegen via Gradle
Voeg de afhankelijkheid toe aan uw apps build.gradle. (Om altijd de nieuwste versie te krijgen, gebruik je het + symbool om de nieuwste updates te krijgen. Via 1.x.+ kun je bijvoorbeeld altijd de nieuwste versies krijgen voor kleine updates)
dependencies {
implementation 'net.consentmanager.sdk:android:x.xx.x'
}
I
Afhankelijkheid toevoegen via Maven
Voeg de afhankelijkheid toe aan uw apps build.gradle. Om altijd de nieuwste versie in maven te krijgen, kunt u verschillende methoden gebruiken om het versiebereik te weigeren. Als u wilt controleren welke versies van de SDK beschikbaar zijn, raadpleegt u deze link. Voor meer informatie verwijzen wij u naar hier.
<dependency>
<groupId>net.consentmanager.sdk</groupId>
<artifactId>android</artifactId>
<version>x.xx.x</version>
</dependency>2. Initialiseren van de SDK
machtigingen
Deze SDK vereist de volgende toestemmingen, zorg ervoor dat u ze toevoegt aan uw AndroidManifest.xml:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />Initialiseren van de ConsentTool - automatisch
Binnen de app-start (meestal de reguliere override onCreate() function) , moet u een instantie van class 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:
Om de ConsentTool te initialiseren, gaat u naar de doelklasse en maakt u een exemplaar van CMPConsentTool, zoals hieronder weergegeven:
// 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)
}
}
Om het exemplaar van CMPConsentTool te maken, moet u het exemplaar configureren. U moet de CODE-ID, het serverdomein, een app-naam en een taal opgeven. Het CODE-ID en serverdomein vindt u in uw consentmanager account onder Menu> Code ophalen. De app-naam kan worden gebruikt om verschillende apps in de te onderscheiden consentmanager rapportage. Voor de taal kunt u een lege tekenreeks ("") gebruiken voor automatische detectie of een tweeletterige taalcode ("EN", "DE", "FR" enzovoort).
Initialiseren van de ConsentTool - handmatig
De SDK biedt, omwille van de flexibiliteit, een manier om de toestemmingslaag handmatig weer te geven, hoewel met de kosten van twee paginaweergaven. 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 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)
Een aangepaste lay-out maken
Voor het maken van een aangepaste lay-out kunt u de CmpUIConfig klasse met verschillende stylingopties. Deze klasse biedt ook enkele vooraf ingestelde lay-outs, zoals
- configureerHalfScreenBottom
- configureerHalfScreenTop
- configureCenterScreen
- configureSmallCenterScreen
- configureerGrootTopScreen
- configurerenLargeBottomScreen
Voor het maken van een aangepaste lay-out biedt de CMP SDK ook verschillende strategieën:
- Dialoogvenster
- Pop-up venster
- fragment
U kunt de strategie wijzigen door de parameter UIConfig in te stellen:
CmpUIConfig.uiStrategy = CmpUIStrategy.DIALOG
CmpUIConfig.uiStrategy = CmpUIStrategy.POPUP
CmpUIConfig.uiStrategy = CmpUIStrategy.ACTIVITY
CmpUIConfig.uiStrategy = CmpUIStrategy.FRAGMENTWij raden u aan een pop-upvenster te gebruiken dat sinds versie 2.3.0 ook als standaard is ingesteld
Twee belangrijke parameters zullen de waarde bepalen Popup en Dialoog gedrag. In onderstaande tabel kunt u de relatie tussen de parameters controleren isFocusable en isOutsideTouchable:
Pop-upgedrag
| Parameter | isFocusable = true |
isFocusable = false |
isOutsideTouchable = true |
Wordt afgewezen bij aanraking van buitenaf. Kan focus krijgen voor invoergebeurtenissen. | Wordt afgewezen bij aanraking van buitenaf. Krijgt geen focus en onderschept geen toetsenbordinvoer. |
isOutsideTouchable = false |
Wijst niet af bij aanraking van buitenaf. Kan focus krijgen en invoergebeurtenissen onderscheppen. | Wijst niet af bij aanraking van buitenaf. Krijgt geen focus en onderschept geen toetsenbordinvoer. |
Dialooggedrag
| Parameter | isFocusable = true |
isFocusable = false |
isOutsideTouchable = true |
Wordt afgewezen bij aanraking van buitenaf (setCanceledOnTouchOutside(true)). Dialoogvensters kunnen standaard worden gefocust. |
Dialogen worden niet genegeerd bij aanraking van buitenaf en gedragen zich mogelijk niet zoals verwacht, omdat dialogen doorgaans focusseerbaar zijn. |
isOutsideTouchable = false |
Wijst niet af bij aanraking van buitenaf (setCanceledOnTouchOutside(false)). Dialoog blijft focusseerbaar en kan invoergebeurtenissen onderscheppen. |
Dialoog wordt niet genegeerd bij aanraking van buitenaf en gedraagt zich mogelijk niet zoals verwacht vanwege het gebrek aan focus. |
Gebruik de fragmentstrategie
R.id.cmpContainer is een framelay-out die er zo uit zou kunnen zien in de activiteitenlay-out-xml in layout/{uw_activiteit}.xml<FrameLayout
android:id="@+id/cmpContainer"
android:layout_width="match_parent"
android:layout_height="400dp"
android:translationZ="90dp"
app:layout_constraintTop_toTopOf="parent" />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 hebben twee parameters, één vereist en één optioneel:
-
id- Tekenreeks 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(Optioneel) - Als de leverancier of het doel een leverancier/doel is dat de IAB TCF-standaard volgt, moet u waar instellen, anders onwaar.
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 openConsentLayer():
cmpManager?.openConsentLayer(context)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:
String 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);Aangepaste gebeurtenisluisteraars
Om extra proceslogica toe te voegen kunt u gebruik maken van Event Listeners. De volgende gebeurtenisluisteraars zijn beschikbaar:
| Naam |
komt voor
|
| AanOpenTerugbellen |
Luisteraar voor gebeurtenis toen CMP werd geopend |
| AanCMPSluitenTerugbellen |
Luisteraar voor gebeurtenis wanneer CMP is gesloten |
| AanCMPNietGeopendTerugbellen |
Luisteraar voor gebeurtenis wanneer CMP niet hoeft te worden geopend |
|
OnErrorTerugbellen |
Luisteraar voor gebeurtenis wanneer er een fout is opgetreden in het toestemmingsbeheerproces. |
| OnButtonClickedCallback |
Luisteraar voor ButtonEvent |
Toestemming voor importeren/exporteren
Om de toestemming te importeren of exporteren kunt u de functies gebruiken exportCMPData() en importCMPData(). Check het voorbeeld hieronder:
// Importing consent data if desired
cmpManager.importCmpString("your_base64_encoded_consentString")
// ... Your code here ...
// Exporting consent data
val consentString: String = cmpManager.exportCmpString()
De consentString die u moet doorgeven, 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 Chrome, 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 Android-activiteit.
// 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
}Logging
Wanneer u onze Android SDK gebruikt, moet u mogelijk voor verschillende doeleinden loggegevens opsporen of analyseren. De door onze SDK gegenereerde logboeken zijn getagd met "CMP", waarmee u eenvoudig alleen de relevante logboeken kunt filteren en bekijken. Deze handleiding biedt stapsgewijze instructies voor het openen van deze logboeken met behulp van Logcat in Android Studio.
Zoek naar het label: typ in de zoekbalk boven de loginstructies CMP om de logboeken met de tag "CMP" eruit te filteren.
Optioneel: Schakel de foutopsporingsmodus in
In CMPConfig, stel in isDebugMode = true.
val config = CmpConfig.apply {
// ... other settings
isDebugMode = true
}
- Maakt gedetailleerdere logboeken mogelijk met de tag 'CMP'.
- Handig voor foutopsporing en analyse.
Troubleshooting
Klasse niet gevonden of NoSuchMethodException:
ProGuard kan soms klassennamen verdoezelen of methoden verwijderen waarnaar via reflectie dynamisch wordt verwezen. Om dit op te lossen, moet u de klassen en methoden specificeren die intact moeten blijven in het ProGuard-configuratiebestand met behulp van de -keep Richtlijn.
Voorbeeld van een ProGuard-configuratie om een specifieke klasse en zijn methoden te behouden:
# 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;
#}
