[Android] 1. consentmanager SDK-integratie

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.

Hoe het werkt

1. Integreer de SDK in de app en configureer de SDK-instellingen
2. Zodra de SDK is geïntegreerd in een app, biedt de SDK functies voor de app-ontwikkelaar om toestemmingsgegevens op te halen
3. Zodra de app start, haalt de SDK automatisch informatie op van de consentmanager servers om de SDK voor te bereiden op het gebruik ervan.
4. Het wordt aanbevolen dat de app bij het opstarten van de app een klasse-instantie maakt CMPConsentTool. Zodra dit is gemaakt, toont de SDK indien nodig automatisch het toestemmingsscherm.
5. Wanneer de app persoonlijke gegevens wil verwerken, moet deze de SDK "vragen" of toestemming is gegeven voor het specifieke doel en de leverancier.

Installatie

Sinds versie 1.7.0 is de SDK-repository verplaatst naar de officiële Maven-repository. De migratiegids is te vinden hier

Vind de compatibele native SDK-versies hier.

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

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. U kunt ze opzoeken hier )

<dependency>
    <groupId>net.consentmanager.sdk</groupId>
    <artifactId>android</artifactId>
    <version>x.xx.x</version>
</dependency>

Met behulp van de bibliotheek

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

Start ConsentTool

Met de app-start (meestal uw viewDidAppear-functie) moet u een instantie van klasse CMPConsentTool maken. Dit haalt automatisch de benodigde gegevens van onze server op en bepaalt of het toestemmingsscherm moet worden weergegeven of niet. Als dat het geval is, toont de SDK op dit punt automatisch het toestemmingsscherm, verzamelt de gegevens en verstrekt de gegevens aan de app. De instantie kan vervolgens worden gebruikt om toestemmingsgegevens van de SDK op te halen om deze in de app te gebruiken.

Om de ConsentTool te starten, gaat u naar uw beoogde klasse en maakt u een instantie van CMPConsentTool zoals hieronder weergegeven:

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

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

De configuratiewaarden kunnen op verschillende manieren worden ingevoegd:

a) SDK-configuratie via CmpConfig

Voeg de volgende regels toe aan je code:

val config = CmpConfig.apply { 
            serverDomain = CMP_DOMAIN
            appName = CMP_APP_NAME
            language = LANG
            id = CODE_ID
        }
cmpManager = CmpManager.createInstance(this, config)

b) SDK-configuratie via createInstance()

Voeg de volgende regel toe aan uw code:

        cmpManager =
            CmpManager.createInstance(
                this,
                config.id,
                config.domain,
                config.appName,
                config.language
            )

Initialiseren en openen van de toestemmingslaag

Om te controleren of de gebruiker toestemming moet geven en om de toestemmingslaag te openen, zijn er verschillende opties. 

Door oproep te initialiseren

De initialize functie is ontworpen om de CMP SDK in te stellen binnen uw applicatiecontext en indien nodig automatisch de toestemmingslaag te controleren en te openen. De initialize kan worden gekoppeld aan het maken van de instantie

cmpManager = CmpManager.createInstance(this, config).initialize(this)

Via CheckAndOpen-oproep

Gelijkaardig als de initialize Functie zal de CheckAndOpenLayer indien nodig de toestemmingslaag openen. 

 cmpManager.checkAndOpenConsentLayer(this)

Handmatig

De check functie biedt een handmatige aanpak om te bepalen of toestemming van de gebruiker vereist is. Het maakt een callback-mechanisme en een optioneel cachemechanisme mogelijk om netwerkverzoeken te verminderen.

        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)

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

Wij raden u aan een pop-upvenster te gebruiken dat sinds versie 2.3.0 ook als standaard is ingesteld

Twee belangrijke parameters zullen de Popup en Dialoog gedrag: 

Pop-upgedrag

Dialooggedrag

Voorbeeld voor fragment:

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

De SDK gebruiken

Controleer op toestemming

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

cmpManager?.hasPurposeConsent(purposeTextState.value)
cmpManager?.hasVendorConsent(vendorTextState.value)                             

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

cmpManager?.openConsentLayer(context)

Toestemmingsinformatie doorgeven aan andere bronnen

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

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:

Toestemming voor importeren/exporteren

Om de toestemming te importeren of exporteren, kunt u de functie gebruiken: exportCMPData(Contextcontext) en importCMPData(Contextcontext, String cmpData). Check het voorbeeld hieronder: 

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

De consentString die u moet doorgeven, moet base64-gecodeerd zijn.

CMP SDK-volgordediagram

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.

Probleem oplossen

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