Info
Inhalt

[Android] 1. consentmanager SDK-Integration

In diesem Dokument finden Sie allgemeine Informationen zur Integration unseres SDK in Ihr Projekt. Weitere Einzelheiten entnehmen Sie bitte unserer API-Referenz Dokumentation.

Seit der Version 1.7.0 wurde unser SDK-Repository in das offizielle Maven-Repository verschoben. Den Migrationsleitfaden finden Sie . Finden Sie die kompatiblen nativen SDK-Versionen .

1. Installation

Der Cavalon Sentinel ist das AutoGyro-Premiummodell mit nebeneinander angeordneten Sitzen, verfügbar mit dem neuen hochmodernen und kraftstoffsparenden Rotax XNUMX iS-Motor. consentmanager SDK für Android-Apps implementiert und bietet Funktionen, um den Benutzer über den Datenschutz zu informieren und die Zustimmung des Benutzers einzuholen und einzuholen. Es ermöglicht App-Entwicklern, das einfach zu integrieren consentmanager Service in ihre App.

Schritte - Hohes Level

    1. Integration und Konfiguration:

      • Integrieren Sie das SDK in Ihre App.
      • Konfigurieren Sie die SDK-Einstellungen entsprechend Ihren Anforderungen.
    2. Erstellen einer Instanz:

      • Erstellen Sie beim Start der App eine Instanz von CMPConsentTool Klasse. Diese Instanz übernimmt den Einwilligungsprozess.
    3. SDK-Initialisierung:
      • Sobald die Instanz bereit ist, ruft das SDK automatisch die erforderlichen Informationen von der Instanz ab consentmanager Server, um sich auf den Betrieb vorzubereiten.
    4. Anzeigen des Einwilligungsbildschirms:

      • Das SDK zeigt bei Bedarf automatisch den Einwilligungsbildschirm an CMPConsentTool Instanz wird erstellt.
    5. Verarbeitung personenbezogener Daten:

      • Sobald die Einwilligungen eingeholt wurden, werden die Informationen gespeichert und stehen für Abfragen über verschiedene Eigenschaften und Methoden zur Verfügung, die von unserem SDK bereitgestellt werden. Sie erhalten Informationen über abgelehnte oder akzeptierte Einwilligungen, Anbieter, Zwecke usw.

    Indem Sie diese Schritte befolgen, stellen Sie sicher, dass Ihre App den Einwilligungsanforderungen entspricht und dass die Nutzereinwilligung ordnungsgemäß verwaltet und gespeichert wird.

Consent Manager Anbieter-SDK-Sequenzdiagramm

Um die oben genannten Schritte zu veranschaulichen, sehen wir uns im Diagramm unten drei mögliche SDK-Sequenzabläufe an. 

1. Beim Erstellen einer Instanz mit dem initialisieren Funktion gibt es zwei mögliche Ergebnisse. Der erste Fall besteht darin, dass die Consentmanger-API das SDK darüber informiert, dass das CMP nicht geöffnet wird, was das auslöst OnCmpNotOpenedCallback. Das zweite Ergebnis ist, wenn die Zustimmungsebene geöffnet wird, sodass der Benutzer damit interagieren kann, und dies löst die aus OnOpenCallback. Sobald der Benutzer seine Zustimmung erteilt und die Zustimmung verarbeitet wird, wird die OnCmpCloseCallback wird genannt.

Bitte beachten Sie, dass die OnErrorCallback wird durch die rot gestrichelten Pfeillinien dargestellt, um Beispiele dafür zu liefern, wann während des Prozesses Fehler auftreten können.

Initialize-Cmp-Sequence-Diagram.png

2. Erstellen einer Instanz und Aufrufen der openAndCheckConsent Funktionen führen zu einem ähnlichen Prozess. Der Unterschied besteht darin, dass Sie durch die Entkopplung der Erstellung der Instanz und der Prüfung für die Consentmanger-API die Möglichkeit erhalten, Geschäftslogik hinzuzufügen und mit der Bibliotheks-API zu interagieren.

3. Erstellen einer Instanz und Aufrufen der offeneSchicht Die Funktion öffnet die Ebene, ohne die zu überprüfen consentmanager, wenn es nötig ist. Bei bereits erteilter Einwilligung werden dem Nutzer die Optionen und Einstellungen aufgezeigt. Der Prozessablauf wird wie folgt aussehen:

openlayer-Cmp-Sequenzdiagramm-.png

Weitere Informationen zu unserer SDK-Versionsübersicht und dem Änderungsprotokoll finden Sie unter diesen Link.

Abhängigkeit über Gradle hinzufügen

Fügen Sie die Abhängigkeit zu build.gradle Ihrer App hinzu. (Um immer die neueste Version zu erhalten, verwenden Sie das +-Symbol, um die neuesten Updates zu erhalten. Sie können beispielsweise immer die neuesten Versionen für kleinere Updates bis 1.x.+ erhalten.)

dependencies {
  implementation 'net.consentmanager.sdk:android:x.xx.x'
}

I

Abhängigkeit über Maven hinzufügen

Fügen Sie die Abhängigkeit zu build.gradle Ihrer Apps hinzu. Um immer die neueste Version in Maven zu erhalten, können Sie verschiedene Methoden verwenden, um den Versionsbereich zu verringern. Um die verfügbaren Versionen des SDK zu überprüfen, besuchen Sie bitte diesen LinkWeitere Informationen finden Sie unter .

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

2. Initialisieren des SDK

Berechtigungen

Für dieses SDK sind die folgenden Berechtigungen erforderlich. Stellen Sie sicher, dass Sie diese zu Ihrer AndroidManifest.xml hinzufügen:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

Initialisieren des ConsentTools – automatisch

Innerhalb des App-Starts (normalerweise der reguläre override onCreate() Funktion) müssen Sie eine Instanz der Klasse erstellen CMPConsentTool. Das initialize() Die Funktion holt automatisch die erforderlichen Daten von unserem Server ab und bestimmt, ob der Zustimmungsbildschirm angezeigt werden muss oder nicht. Wenn dies der Fall ist, zeigt das SDK an dieser Stelle automatisch den Zustimmungsbildschirm an, sammelt die Daten und stellt sie der App zur Verfügung. Die Instanz kann dann verwendet werden, um Zustimmungsdetails vom SDK abzurufen, um sie in der App zu verwenden.Beispiel für die Initialisierung unter Verwendung des automatischen Verhaltens der initialize() Verfahren:

Um das ConsentTool zu initialisieren, gehen Sie zu Ihrer Zielklasse und erstellen Sie eine Instanz von CMPConsentTool wie unten gezeigt:

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

    // ... open layer and ask for purpose

    private void openConsentLayerAndCheckPurpose() {
        cmpManager.openConsentLayer(getApplication());

        if (cmpManager.hasPurposeConsent("PURPOSE_ID")) {
            Log.d("CmpDemoActivity", "Has purpose consent");
        } else {
            Log.d("CmpDemoActivity", "Does not have purpose consent");
        }
    }
}

Um die Instanz von CMPConsentTool zu erstellen, müssen Sie die Instanz konfigurieren. Sie müssen die CODE-ID, die Serverdomäne, einen App-Namen und eine Sprache angeben. Die CODE-ID und die Serverdomäne finden Sie in Ihrem consentmanager Konto unter Menü> Code abrufen. Der App-Name kann verwendet werden, um verschiedene Apps in der zu unterscheiden consentmanager Berichterstattung. Für die Sprache können Sie entweder eine leere Zeichenfolge ("") zur automatischen Erkennung oder einen aus zwei Buchstaben bestehenden Sprachcode ("EN", "DE", "FR" usw.) verwenden.

Initialisierung des ConsentTools – manuell

Aus Gründen der Flexibilität bietet das SDK eine Möglichkeit, die Zustimmungsebene manuell anzuzeigen, wie unten gezeigt: 

        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)

Erstellen eines benutzerdefinierten Layouts

Zum Erstellen eines benutzerdefinierten Layouts können Sie das verwenden CmpUIConfig Klasse mit verschiedenen Styling-Optionen. Diese Klasse bietet auch einige voreingestellte Layouts wie 

  • configureHalfScreenBottom
  • configureHalfScreenTop
  • configureCenterScreen
  • configureSmallCenterScreen
  • configureLargeTopScreen
  • configureLargeBottomScreen

Für die Erstellung eines benutzerdefinierten Layouts bietet das CMP SDK auch verschiedene Strategien an:

  • Dialogfenster
  • Pop-up-Fenster
  • Fragment

Sie können die Strategie ändern, indem Sie den Parameter UIConfig festlegen: 

CmpUIConfig.uiStrategy = CmpUIStrategy.DIALOG
CmpUIConfig.uiStrategy = CmpUIStrategy.POPUP
CmpUIConfig.uiStrategy = CmpUIStrategy.ACTIVITY
CmpUIConfig.uiStrategy = CmpUIStrategy.FRAGMENT

Wir empfehlen die Verwendung eines Popup-Fensters, das seit Version 2.3.0 auch als Standard festgelegt ist

Zwei wichtige Parameter bestimmen die Pop-up und Dialog Verhalten. In der folgenden Tabelle können Sie die Beziehung zwischen den Parametern überprüfen isFocusable und isOutsideTouchable

Popup-Verhalten
Parameter isFocusable = true isFocusable = false
isOutsideTouchable =  true Wird bei Berührung von außen abgewiesen. Kann den Fokus für Eingabeereignisse gewinnen. Wird bei Berührung von außen abgewiesen. Erhält keinen Fokus und fängt Tastatureingaben nicht ab.
isOutsideTouchable = false Lässt sich bei Berührung von außen nicht abweisen. Kann sich konzentrieren und Eingabeereignisse abfangen. Lässt sich bei Berührung von außen nicht abweisen. Erhält keinen Fokus und fängt Tastatureingaben nicht ab.

 

 

 

Dialogverhalten
Parameter isFocusable = true isFocusable = false
isOutsideTouchable =  true Wird bei Berührung von außen abgewiesen (setCanceledOnTouchOutside(true)). Der Dialog ist standardmäßig fokussierbar. Der Dialog wird bei Berührungen von außen nicht abgewiesen und verhält sich möglicherweise nicht wie erwartet, da Dialoge normalerweise fokussierbar sind.
isOutsideTouchable = false Lässt sich bei Berührung von außen nicht abweisen (setCanceledOnTouchOutside(false)). Der Dialog bleibt fokussierbar und kann Eingabeereignisse abfangen. Der Dialog lehnt Berührungen von außen nicht ab und verhält sich aufgrund mangelnder Fokussierbarkeit möglicherweise nicht wie erwartet.
Verwendung der Fragment-Strategie
R.id.cmpContainer ist ein Framelayout, das in der Aktivitätslayout-XML in layout/{your_activity}.xml so aussehen könnte

<FrameLayout
    android:id="@+id/cmpContainer"
    android:layout_width="match_parent"
    android:layout_height="400dp"
    android:translationZ="90dp"
    app:layout_constraintTop_toTopOf="parent" />

3. Verwendung des SDK

Um zu überprüfen, ob ein Anbieter oder ein Zweck eine Einwilligung hat, können Sie die beiden folgenden Methoden verwenden:

if (cmpManager.hasPurposeConsent("52")) {
    if (cmpManager.hasVendorConsent("s26")) {
        // Add your logic here
    }
}

Beide Methoden hasPurposeConsent und hasVendorConsent haben zwei Parameter, einen erforderlichen und einen optionalen:

  • id – Zeichenfolge der Anbieter- oder Zweck-ID. Bitte beachten Sie, dass Anbieter-IDs unterschiedliche Formate haben können („123“, „s123“ und „c123“). Bitte überprüfen Sie dies noch einmal mit Menü> Anbieter und Menü> Zwecke in Ihrem consentmanager Konto.
  • isIABVendor / isIABPurpose (Optional) – Wenn es sich bei dem Anbieter oder Zweck um einen Anbieter/Zweck handelt, der dem IAB TCF-Standard folgt, müssen Sie „true“ festlegen, andernfalls „false“.

Denken Sie daran: Alle Anbieter, die nicht zum IAB gehören, haben IDs, die mit einem "s" oder "c" beginnen (z. B. "s123"). Anbieter, die zum IAB gehören, haben IDs, die nicht mit einem "s" oder "c" beginnen.

Öffnen Sie den Zustimmungsbildschirm erneut

Damit der Benutzer die Auswahl ändern kann, können Sie einfach anrufen openConsentLayer():

cmpManager?.openConsentLayer(context)

In einigen Fällen kann eine native App Webviews enthalten, um bestimmte Dinge wie Werbung oder Inhalte anzuzeigen. Um die Einwilligungsinformationen vom SDK an die Webansicht zu übermitteln, nutzen Sie bitte die Funktion:

String consentData = cmpConsentTool?.exportCmpString();

Dadurch werden die Zustimmungsinformationen und alle weiteren Daten exportiert, die vom CMP benötigt werden. Sie können diese Informationen dann an das CMP in Ihrer Webansicht übergeben, indem Sie sie der in der Webansicht aufgerufenen URL hinzufügen:

myWebView.loadURL("https://mywebsite.com/....#cmpimport=" + consentData);

Benutzerdefinierte Ereignislistener

Um zusätzliche Prozesslogik hinzuzufügen, können Sie Event Listener verwenden. Folgende Ereignis-Listener sind verfügbar:

Name und Vorname

Tritt auf

 

OnOpenCallback

Listener für Ereignis beim Öffnen von CMP

OnCMPCloseCallback

Listener für Ereignis, wenn CMP geschlossen ist

OnCMPNotOpenedCallback

Listener für Ereignis, wenn CMP nicht geöffnet werden muss

OnErrorCallback

Listener für Event, wenn ein Fehler im Consent Management-Prozess auftritt.

OnButtonClickedCallback

Listener für ButtonEvent

Zustimmung zum Importieren/Exportieren

Zum Importieren oder Exportieren der Einwilligung können Sie die Funktionen nutzen exportCMPData() und importCMPData(). Überprüfen Sie das folgende Beispiel: 

Der zu übergebende ConsentString sollte base64-codiert sein.

Um die Funktionalität zu implementieren, bei der bestimmte Domänen auf die Whitelist gesetzt werden und beim Zugriff innerhalb der Consent Platform (CMP) WebView nicht in einem externen Browser wie Chrome, sondern innerhalb der WebView selbst geöffnet werden, können Sie einen Rückrufmechanismus implementieren, um benutzerdefinierte Aktionen basierend auf dem auszuführen Domäne, beispielsweise das Öffnen einer Android-Aktivität.

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

Protokollierung

Wenn Sie unser Android SDK verwenden, müssen Sie möglicherweise für verschiedene Zwecke Protokollinformationen debuggen oder analysieren. Die von unserem SDK generierten Protokolle sind mit „CMP“ gekennzeichnet, sodass Sie einfach nur die relevanten Protokolle filtern und anzeigen können. Diese Anleitung enthält Schritt-für-Schritt-Anleitungen für den Zugriff auf diese Protokolle mit Logcat in Android Studio.

Suchen Sie nach dem Tag: Geben Sie in die Suchleiste über den Protokollanweisungen ein CMP um die mit „CMP“ gekennzeichneten Protokolle herauszufiltern.

Optional: Aktivieren Sie den Debug-Modus

In CMPConfig, einstellen isDebugMode = true.

val config = CmpConfig.apply {
    // ... other settings
    isDebugMode = true
}
  • Ermöglicht detailliertere Protokolle mit dem Tag „CMP“.
  • Nützlich zum Debuggen und Analysieren.

Problemlösung

Klasse nicht gefunden oder NoSuchMethodException:

ProGuard kann manchmal Klassennamen verschleiern oder Methoden entfernen, auf die dynamisch über Reflektion verwiesen wird. Um dies zu beheben, müssen Sie mithilfe von die Klassen und Methoden angeben, die in der ProGuard-Konfigurationsdatei intakt bleiben sollen -keep Richtlinie.

Beispielhafte ProGuard-Konfiguration zum Beibehalten einer bestimmten Klasse und ihrer Methoden:

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

 

Nach oben