Info
Content

[Android] 1. consentmanager SDK-integratie

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.

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

    1. Integratie en configuratie:

      • Integreer de SDK in uw app.
      • Configureer de SDK-instellingen volgens uw behoeften.
    2. Een exemplaar maken:

      • Maak bij het opstarten van de app een exemplaar van het CMPConsentTool klas. Deze instantie zal het toestemmingsproces afhandelen.
    3. 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.
    4. Het toestemmingsscherm weergeven:

      • De SDK geeft indien nodig automatisch het toestemmingsscherm weer wanneer de CMPConsentTool exemplaar is gemaakt.
    5. 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.

Initialiseer-Cmp-Sequence-Diagram.png

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:

openlayer-Cmp-Sequence-Diagram-.png

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, zoals hieronder gedemonstreerd: 

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

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)

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: 

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

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

 

Terug naar boven