Info
Inhalt

[Android] 0. Migrationsleitfaden

Version 1.7.33

Migrationsleitfaden zum neuen SDK-Repository

Das SDK-Repository wurde in das offizielle Maven-Repository verschoben. Hier finden Sie eine Schritt-für-Schritt-Anleitung, wie Sie Ihr Projekt aktualisieren, um das neue Repository und die neueste Version des SDK zu verwenden.

Vor der Migration

Schritt 1: Jitpack-Repository hinzufügen

Fügen Sie das Jitpack-Repository zu Ihrem Root-Build.gradle am Ende der Repositorys hinzu:

allprojects {  
  repositories {    
    ...    
    maven { url 'https://jitpack.io' }  
  }
}

Schritt 2: Abhängigkeit hinzufügen

Fügen Sie die Abhängigkeit zum build.gradle Ihrer App hinzu, um die neueste Version des SDK zu erhalten:

dependencies {
  implementation 'org.bitbucket.consentmanager:android-consentmanager:1.5.+'
}
Nach der Migration

Schritt 1: Jitpack-Repository entfernen

Entfernen Sie das Jitpack-Repository aus Ihrem Root-build.gradle:

allprojects {  
  repositories {    
    ...    
    // Remove the following line 
    maven { url 'https://jitpack.io' }  
  }
}

Schritt 2: Offizielles Maven-Repository hinzufügen

Ersetzen Sie die alte Abhängigkeit durch die neue Abhängigkeit aus dem offiziellen Maven-Repository:

dependencies {
  implementation 'net.consentmanager.sdk:android:1.7.33'
}

Jetzt ist Ihr Projekt aktualisiert, um das neue offizielle Maven-Repository und die neueste Version des SDK (1.7.33) zu verwenden. Stellen Sie sicher, dass Sie Ihr Projekt synchronisieren und alle anderen Konfigurationen oder Codes aktualisieren, die möglicherweise von dieser Migration betroffen sind.

Von 1.xx bis 1.6.3

Es ist wichtig zu beachten, dass ein Upgrade auf eine neue Version einer App möglicherweise nicht immer reibungslos verläuft. In einigen Fällen müssen Sie möglicherweise Ihren Code ändern oder Ihre Abhängigkeiten aktualisieren, um sicherzustellen, dass Ihre App ordnungsgemäß funktioniert.

Änderungen zur Überprüfung auf Consentlayer

In der vorherigen Version des CMP SDK war die Prüfung für den Consentlayer in die Hauptkonstruktorfunktion integriert. In der neuen Version der App haben wir die Prüfung in einer neuen Funktion namens initialize() getrennt. Diese Änderung wurde vorgenommen, um die Zuverlässigkeit und Konsistenz der Zustimmungsschichtprüfung zu verbessern.

Um die Funktion initialize() zu verwenden, können Sie createInstance() mit den erforderlichen Parametern aufrufen und die Funktion initialize() dem zurückgegebenen Objekt hinzufügen:

createInstance(
    applicationContext,
    CMP_ID,
    CMP_DOMAIN,
    CMP_APP_NAME,
    LANG
).initialize(this)

In diesem Beispiel rufen wir createInstance() auf, um die Zustimmungsebene zu initialisieren. Die Initialisierungsfunktion fordert die an consentmanager und bestimmt, ob die Zustimmungsebene angezeigt werden muss oder nicht.

Wenn Sie zuvor die automatische Aktualisierung für die Zustimmungsebene in Ihrer App verwendet haben, müssen Sie Ihren Code ändern, um stattdessen die Funktion initialize() zu verwenden. Dadurch wird sichergestellt, dass der Consentlayer in der neuen Version der App konsistent und zuverlässig geprüft wird. Ohne initialize() wird nur die Instanz erstellt.

Wenn Sie ein benutzerdefiniertes Layout verwenden, achten Sie bitte darauf, die Aktivitätsinstanz bei der Initialisierung zu übergeben. Um sicherzustellen, dass das Fragment korrekt zur Aktivität hinzugefügt wird. 

Änderungen an Rückrufen

In der vorherigen Version des CMP SDK hatten wir verschiedene Callbacks, deren Verwendung verwirrend war. In der neuen Version können nun vier separate Callback-Funktionen implementiert werden. Diese Callback-Funktion muss nur einmal zur Instanz hinzugefügt werden und ist über alle API-Interaktionen verfügbar.

Die vier Callbacks heißen wie folgt:

  • onOpenCallback: Diese Funktion wird aufgerufen, wenn der Consentlayer erfolgreich geöffnet wurde.
  • OnCloseCallback: Diese Funktion wird aufgerufen, wenn der Consentlayer geschlossen wird.
  • OnCMPNotOpenedCallback: Diese Funktion wird aufgerufen, wenn der Consentlayer nicht geöffnet werden kann.
  • OnErrorCallback: Diese Funktion wird aufgerufen, wenn bei der Interaktion mit dem Consentlayer ein Fehler auftritt.

Das OnErrorCallback -Funktion wird für alle gängigen Fehler anstelle der getrennten Fehlerrückruffunktionen aufgerufen, die in der vorherigen Version der App verwendet wurden.

Um diese Callbacks zu verwenden, können Sie sie wie folgt im Konstruktor der Zustimmungsschicht implementieren:

createInstance(
    applicationContext,
    CMP_ID,
    CMP_DOMAIN,
    CMP_APP_NAME,
    LANG,
    openListener = object : OnOpenCallback {
        override fun onWebViewOpened() {
            Log.d(TAG, "opened callback")
        }
    },
    closeListener = object : OnCloseCallback {
        override fun onWebViewClosed() {
            Log.d(TAG, "closed callback")
        }
    },
    cmpNotOpenedCallback = object : OnCMPNotOpenedCallback {
        override fun onCMPNotOpened() {
            Log.d(TAG, "cmp not opened")
        }
    },
    errorCallback = object : OnErrorCallback {
        override fun errorOccurred(message: String) {
            Log.d(TAG, "error occurred")
        }
    }

).
Neue API-Funktionen

In der vorherigen Version des CMP SDK wurden keine Funktionen bereitgestellt, um Informationen über die aktivierten und deaktivierten Anbieter des Benutzers abzurufen oder Anbieter- und Zwecklisten zu aktivieren und zu deaktivieren. In der neuen Version der App haben wir mehrere neue API-Funktionen hinzugefügt, die es Ihnen ermöglichen, tiefer mit der Einwilligungsschicht zu interagieren.

Die neuen API-Funktionen sind:

  • getAgreedVendors: Diese Funktion gibt eine Zeichenfolge zurück, die die IDs der Anbieter enthält, denen der Benutzer zugestimmt hat.
  • getAgreedVendorList: Diese Funktion gibt eine Liste der IDs der Anbieter zurück, denen der Benutzer zugestimmt hat.
  • getDisabledVendors: Diese Funktion gibt eine Liste der IDs der Anbieter zurück, die der Benutzer deaktiviert hat.
  • enableVendorList: Diese Funktion aktiviert die angegebenen Anbieter.
  • disableVendorList: Diese Funktion deaktiviert die angegebenen Anbieter.
  • enablePurposeList: Diese Funktion aktiviert die angegebenen Zwecke und aktualisiert die Anbieterliste standardmäßig.
  • disablePurposeList: Diese Funktion deaktiviert die angegebenen Zwecke und aktualisiert die Anbieterliste standardmäßig.
  • rejectAll: Diese Funktion simuliert die Ablehnung aller Anbieter und Zwecke durch einen Benutzer. Es erfordert eine OnConsentReceivedCallback Callback-Funktion, um die Asynchronität der API zu behandeln.
  • acceptAll: Diese Funktion simuliert die Zustimmung eines Benutzers zu allen Anbietern und Zwecken. Es erfordert eine OnConsentReceivedCallback Callback-Funktion, um die Asynchronität der API zu behandeln.

Das rejectAll und acceptAll Funktionen erfordern die Bereitstellung einer Callback-Funktion, um die Asynchronität der API zu handhaben. Sie sollten jede Geschäftslogik, die von den Ergebnissen dieser Funktionen abhängt, innerhalb der Callback-Funktionen implementieren, um sicherzustellen, dass Ihre App ordnungsgemäß aktualisiert wird.

Änderungen an der importConsent-Funktion

In der vorherigen Version des CMP SDK wurde die importCMPData -Funktion wurde verwendet, um die cmp-Zustimmungszeichenfolge in die freigegebenen Einstellungen der App zu importieren. In der neuen Version der App wurde diese Funktion aktualisiert. Diese Funktion wird mit synchronisiert Consentmanager Backend für bessere Konsistenz und weniger Fehler.

Um die Funktionalität der aktualisierten zu gewährleisten importCMPData Funktion wurde ein Callback implementiert. Dieser Callback informiert Sie darüber, ob der Import erfolgreich war oder nicht. Jegliche Geschäftslogik, die vom Ergebnis abhängt, sollte ebenfalls in diesem Callback implementiert werden.

Die aktualisierte Funktion hat die folgende Signatur:

fun importCMPData(context: Context, cmpData: String, callback: CmpImportCallback)

Sie können diese Funktion verwenden, um eine vollständige Einwilligungszeichenfolge, die von einem ConsentWebView generiert wurde, in die gemeinsamen Einstellungen Ihres Geräts zu importieren. Um die Funktion aufzurufen, müssen Sie die folgenden Parameter angeben:

  • context: Der App-Kontext
  • cmpData: Die zu importierende Einwilligungszeichenfolge, in Base64 codiert
  • callback: Eine Rückruffunktion, um das Ergebnis des Importvorgangs zu erhalten

Wenn der Import erfolgreich ist, ruft die Funktion die onImportResult Methode des Rückrufs mit der success Parametersatz auf true und eine Meldung, die anzeigt, dass der Import erfolgreich war. Wenn der Import nicht erfolgreich ist, ruft die Funktion die auf onImportResult Methode des Rückrufs mit der success Parametersatz auf false und eine Meldung, die angibt, warum der Import nicht erfolgreich war.

Jegliche Geschäftslogik, die vom Ergebnis des Importvorgangs abhängt, sollte im Rückruf implementiert werden, um sicherzustellen, dass Ihre App ordnungsgemäß aktualisiert wird.

Änderungen an der Programmiersprache Kotlin

Die Migration zum neuen Kotlin SDK erfordert einige Änderungen bei der Verwendung des SDK. Die App wurde von einer Java-Bibliothek in eine Kotlin-Bibliothek umgestaltet, daher gibt es einige Änderungen, die Sie beachten sollten.

Bei Java-Anwendungen müssen Sie darauf achten statische Methoden und überladene Funktionen. In einigen Teilen des SDK müssen Sie möglicherweise die Companion Objekt für den Zugriff auf statische Methoden, und es ist möglicherweise nicht möglich, die SDK-Manager-Klasse auf die gleiche Weise wie zuvor zu instanziieren.

Wir haben versucht sicherzustellen, dass die Unterschiede für die Migration minimal sind, aber es wird empfohlen, dass Sie die Dokumentation und den Beispielcode für das aktualisierte Kotlin SDK sorgfältig prüfen, um alle Änderungen in der Verwendung zu verstehen. Überprüfen Sie außerdem Ihre vorhandene Codebasis und aktualisieren Sie alle Aufrufe veralteter oder entfernter Methoden, um Probleme während des Migrationsprozesses zu vermeiden.

Insgesamt sollte die Migration auf das neue Kotlin SDK unkompliziert sein. Die Änderungen wurden vorgenommen, um die Funktionalität und Konsistenz des SDK zu verbessern. Es ist jedoch wichtig, Ihre Codebasis nach der Migration gründlich zu testen, um sicherzustellen, dass alles ordnungsgemäß funktioniert.

Von 1.5.7 zu 1.6.0
Aktualisieren Sie CMP-IDs auf Code-IDs für die weitere Verwendung des SDK

Wir nehmen einige Änderungen an den CMP-IDs vor, die zur Identifizierung unseres CMP verwendet werden. Damit Sie unser SDK weiterhin nutzen können, ist eine Aktualisierung der CMP-IDs mit dem neuen Code-IDs die im Admin-Bereich für den SDK-Code zu finden ist.

Wie aktualisieren Sie die CMP-IDs?

Um die CMP-IDs zu aktualisieren, müssen Sie sich im Admin-Bereich für die anmelden Consentmanager und finden Sie die neuen Code-IDs (Code abrufen -> Einrichtung für Apps (Android/iOS)). Sobald Sie die neue haben Code-ID, Sie können das ersetzen CMP-ID in Ihrem SDK-Code damit

SetupCodeId.png

Wir empfehlen Ihnen, Ihren SDK-Code mit dem neuen zu aktualisieren Code-IDs so schnell wie möglich, um sicherzustellen, dass Sie unser CMP weiterhin ohne Unterbrechung nutzen können.

Bitte beachten Sie, dass das End of Life für die CMP-ID geplant ist Dezember 2023. Das bedeutet, dass die CMP-ID ab diesem Datum nicht mehr unterstützt wird. Wenn Sie Fragen oder Bedenken zu dieser Migration haben, wenden Sie sich bitte an unser Support-Team, um Unterstützung zu erhalten!

Update auf neue Benennungskonventionen für Schnittstellen

Wir haben einige Änderungen an unseren Namenskonventionen für Schnittstellen vorgenommen, um die API der nativen SDKs zu synchronisieren und für ein besseres Domänenverständnis. Infolge dieser Änderungen wurden einige API-Signaturen geändert und einige neue Methoden eingeführt.

Hier sind die vorgenommenen Änderungen:

Alte API-Signatur Neue API-Signatur
checkAndOpenCmpLayer();

checkAndOpenCmpLayer(appInterface: string);

getLastConsentString();

getConsentstring();

exportCMPData();

exportCmpString();

importCMPData(cmpData: string);

importCmpString(cmpString: string);

getAgreedVendor();

getEnabledVendors();

Fehler-Callback mit CMP-Fehlertypen aktualisieren

Wir führen CMP-Fehlertypen in den Fehler-Callback ein, um eine größere Flexibilität zu bieten und je nach Art des auftretenden Fehlers ein differenzierteres Verhalten zu ermöglichen. Mit diesem Update können Sie verschiedene Arten von Fehlern effektiver behandeln, was dazu beiträgt, dass Ihre Benutzer die bestmögliche Erfahrung machen.

Was sind CMP-Fehlertypen?

CMP-Fehlertypen sind eine Reihe von Fehlertypen, die in den Fehlerrückruf eingeführt wurden. Diese Fehlertypen werden verwendet, um den aufgetretenen Fehlertyp zu identifizieren, und sie können verwendet werden, um je nach Fehlertyp unterschiedliche Verhaltensweisen auszulösen.

Die vier eingeführten CMP-Fehlertypen sind:

  • Netzwerkfehler
  • Zeitüberschreitung
  • ConsentReadWriteError
  • ConsentLayerError

Wie wirkt sich diese Änderung auf Ihren Code aus?

Zur Unterstützung der neuen CMP-Fehlertypen wurde die Signatur des Fehler-Callbacks aktualisiert. Die neue Signatur lautet:

fun errorOccurred(type: CmpError, message: String)

Sie müssen Ihren Code aktualisieren, um die neue Signatur zu verwenden und die verschiedenen Fehlertypen angemessen zu behandeln.

Wie können Sie mit verschiedenen Arten von Fehlern umgehen?

Um verschiedene Arten von Fehlern zu behandeln, können Sie den CmpError-Parameter verwenden, der an den Fehlerrückruf übergeben wird. Dieser Parameter enthält die Art des aufgetretenen Fehlers, mit dem Sie verschiedene Verhaltensweisen auslösen können.

Beispielsweise können Sie einen NetworkError anders behandeln als einen ConsentLayerError. Mit dem Parameter CmpError können Sie die Art des Fehlers bestimmen und das entsprechende Verhalten auslösen.

Ein Beispiel für eine Implementierung kann wie folgt aussehen: 

override fun errorOccurred(type: CmpError, message: String) {
                    when (type) {
                        CmpError.NetworkError -> {
                            Log.e(TAG, "Network error: $message")
                            // Handle network error
                        }
                        CmpError.TimeoutError -> {
                            Log.e(TAG, "Timeout error: $message")
                            // Handle timeout error
                        }
                        CmpError.ConsentReadWriteError -> {
                            Log.e(TAG, "Consent read/write error: $message")
                            // Handle consent read/write error
                        }
                        CmpError.ConsentLayerError -> {
                            Log.e(TAG, "Consentlayer error: $message")
                            // Handle consentlayer error
                        }
                        else -> {
                            Log.d(TAG, "default")
                        }
                    }
                }
Neuer Callback zur Identifizierung von User-Button-Events: 

Wir haben eine neue Callback-Funktion hinzugefügt, OnCmpButtonClickedCallback, die verwendet werden kann, um die Interaktionen der Benutzer mit der Zustimmungsschicht zu bestimmen, indem die spezifischen Schaltflächenklickereignisse erfasst werden. Dieser Rückruf hilft Entwicklern, Einblicke in die Benutzereinstellungen zu gewinnen und die Benutzererfahrung entsprechend anzupassen.

Ein Beispiel für eine Implementierung kann wie folgt aussehen: 

            cmpButtonClickedCallback = object : OnCmpButtonClickedCallback {
                override fun onButtonClicked(event: CmpButtonEvent) {
                    when (event) {
                        CmpButtonEvent.RejectAll -> {
                            Log.d(TAG, "User clicked Reject all")
                        }
                        CmpButtonEvent.Save -> {
                            Log.d(TAG, "User saved custom settings")
                        }
                        CmpButtonEvent.AcceptAll -> {
                            Log.d(TAG, "User clicked accept all")
                        }
                        CmpButtonEvent.Close -> {
                            Log.d(TAG, "user closed layer without giving consent")
                        }
                        else -> {
                            Log.d(TAG, "no button event logic needed")
                        }
                    }
                }
            }
Nach oben