[Android] 1. consentmanager SDK-integration

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.

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å

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

Vi 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

Dialogbeteende

Använder strategin Fragment

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

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