[Android] 0. Migratiegids

versie 1.7.33

Migratiehandleiding naar nieuwe SDK-repository

De SDK-repository is verplaatst naar de officiële Maven-repository. Hier vindt u een stapsgewijze handleiding voor het bijwerken van uw project zodat u de nieuwe opslagplaats en de nieuwste versie van de SDK kunt gebruiken.

Voor de migratie

Stap 1: Voeg Jitpack-repository toe

Voeg de Jitpack-repository toe aan je root build.gradle aan het einde van de repository's:

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

Stap 2: Voeg afhankelijkheid toe

Voeg de afhankelijkheid toe aan build.gradle van uw app om de nieuwste versie van de SDK te verkrijgen:

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

Na migratie

Stap 1: Verwijder de Jitpack-repository

Verwijder de Jitpack-repository uit uw root build.gradle:

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

Stap 2: Voeg de officiële Maven-repository toe

Vervang de oude afhankelijkheid door de nieuwe afhankelijkheid uit de officiële Maven-repository:

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

Nu is uw project bijgewerkt om de nieuwe officiële Maven-repository en de nieuwste versie van de SDK (1.7.33) te gebruiken. Zorg ervoor dat u uw project synchroniseert en eventuele andere configuraties of code bijwerkt die mogelijk door deze migratie worden beïnvloed.

Van 1.xx tot 1.6.3

Het is belangrijk op te merken dat het upgraden naar een nieuwe versie van een app niet altijd een naadloos proces is. In sommige gevallen moet u mogelijk uw code wijzigen of uw afhankelijkheden bijwerken om ervoor te zorgen dat uw app correct werkt.

Wijzigingen om te controleren op Consentlayer

In de vorige versie van de CMP SDK was de controle voor de toestemmingslaag geïntegreerd in de hoofdconstructorfunctie. In de nieuwe versie van de app hebben we de check gescheiden in een nieuwe functie genaamd initialize(). Deze wijziging is aangebracht om de betrouwbaarheid en consistentie van de toestemmingslaagcontrole te verbeteren.

Om de functie initialize() te gebruiken, kunt u createInstance() aanroepen met de vereiste parameters en de functie initialize() toevoegen aan het geretourneerde object:

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

In dit voorbeeld roepen we createInstance() aan om de consentlayer te initialiseren. De initialisatiefunctie vraagt ​​om het consentmanager en bepaalt of de toestemmingslaag getoond moet worden of niet.

Als u voorheen de automatische update voor de toestemmingslaag in uw app gebruikte, moet u uw code aanpassen om in plaats daarvan de initialize()-functie te gebruiken. Dit zorgt ervoor dat de toestemmingslaag consistent en betrouwbaar wordt gecontroleerd in de nieuwe versie van de app. Zonder initialize() wordt alleen de instantie gemaakt.

Als u een aangepaste lay-out gebruikt, let er dan op dat u de activiteitsinstantie doorgeeft bij de initialisatie. Om ervoor te zorgen dat het fragment correct wordt toegevoegd aan de activiteit. 

Wijzigingen in terugbelverzoeken

In de vorige versie van de CMP SDK hadden we verschillende callbacks die verwarrend waren om te gebruiken. In de nieuwe versie zijn er nu vier afzonderlijke callback-functies die kunnen worden geïmplementeerd. Deze callback-functie hoeft slechts één keer aan de instantie te worden toegevoegd en is beschikbaar via alle API-interacties.

De vier callbacks worden als volgt genoemd:

• onOpenCallback: Deze functie wordt aangeroepen wanneer de toestemmingslaag succesvol is geopend.
• OnCloseCallback: Deze functie wordt aangeroepen als de toestemmingslaag gesloten is.
• OnCMPNotOpenedCallback: Deze functie wordt aangeroepen als de toestemmingslaag niet geopend kan worden.
• OnErrorCallback: Deze functie wordt aangeroepen wanneer er een fout optreedt tijdens interactie met de toestemmingslaag.

De OnErrorCallback functie wordt aangeroepen voor alle veelvoorkomende fouten, in plaats van de afzonderlijke foutterugbelfuncties die in de vorige versie van de app werden gebruikt.

Om deze callbacks te gebruiken, kun je ze als volgt implementeren in de constructor van de toestemmingslaag:

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

).

Nieuwe API-functies

In de vorige versie van de CMP SDK waren er geen functies om informatie op te halen over de ingeschakelde en uitgeschakelde leveranciers van de gebruiker, of om leveranciers- en doellijsten in en uit te schakelen. In de nieuwe versie van de app hebben we verschillende nieuwe API-functies toegevoegd waarmee je dieper kunt communiceren met de toestemmingslaag.

De nieuwe API-functies zijn:

• getAgreedVendors: Deze functie retourneert een tekenreeks met de ID's van de leveranciers waarmee de gebruiker heeft ingestemd.
• getAgreedVendorList: Deze functie retourneert een lijst met de ID's van de leveranciers waarmee de gebruiker heeft ingestemd.
• getDisabledVendors: Deze functie retourneert een lijst met de ID's van de leveranciers die de gebruiker heeft uitgeschakeld.
• enableVendorList: Deze functie schakelt de opgegeven leveranciers in.
• disableVendorList: Deze functie schakelt de opgegeven leveranciers uit.
• enablePurposeList: Deze functie maakt de gespecificeerde doeleinden mogelijk en werkt standaard de leverancierslijst bij.
• disablePurposeList: Deze functie schakelt de gespecificeerde doeleinden uit en werkt de leverancierslijst standaard bij.
• rejectAll: Deze functie simuleert de afwijzing door een gebruiker van alle leveranciers en doeleinden. Het vereist een OnConsentReceivedCallback callback-functie om de asynchroniciteit van de API af te handelen.
• acceptAll: Deze functie simuleert de acceptatie door een gebruiker van alle leveranciers en doeleinden. Het vereist een OnConsentReceivedCallback callback-functie om de asynchroniciteit van de API af te handelen.

De rejectAll en acceptAll functies vereisen een callback-functie om de asynchroniciteit van de API af te handelen. U moet alle bedrijfslogica implementeren die afhankelijk is van de resultaten van deze functies binnen de callback-functies om ervoor te zorgen dat uw app correct wordt bijgewerkt.

Wijzigingen in de functie importConsent

In de vorige versie van de CMP SDK was de importCMPData functie werd gebruikt om de cmp-toestemmingsreeks te importeren in de gedeelde voorkeuren van de app. In de nieuwe versie van de app is deze functie geüpdatet. Deze functie wordt gesynchroniseerd met de Consentmanager Backend voor betere consistentie en minder fouten.

Om de functionaliteit van de bijgewerkte importCMPData functie is er een callback geïmplementeerd. Deze callback informeert u of de import succesvol was of niet. Elke bedrijfslogica die afhankelijk is van het resultaat, moet ook in deze callback worden geïmplementeerd.

De bijgewerkte functie heeft de volgende handtekening:

U kunt deze functie gebruiken om een ​​tekenreeks met volledige toestemming die door een ConsentWebView is gegenereerd, te importeren in de gedeelde voorkeuren van uw apparaat. Om de functie aan te roepen, moet u de volgende parameters opgeven:

• context: De app-context
• cmpData: De tekenreeks voor toestemming om te importeren, gecodeerd in base64
• callback: Een callback-functie om het resultaat van de importbewerking te ontvangen

Als het importeren is gelukt, roept de functie het onImportResult methode van terugbellen met de success parameter ingesteld op true en een bericht dat aangeeft dat het importeren is gelukt. Als het importeren niet is gelukt, roept de functie het onImportResult methode van terugbellen met de success parameter ingesteld op false en een bericht dat aangeeft waarom het importeren niet is gelukt.

Alle bedrijfslogica die afhankelijk is van het resultaat van de importbewerking, moet worden geïmplementeerd in de callback om ervoor te zorgen dat uw app correct wordt bijgewerkt.

Wijzigingen in de programmeertaal Kotlin

Migratie naar de nieuwe Kotlin SDK vereist enkele wijzigingen in de manier waarop u de SDK gebruikt. De app is geherstructureerd van een Java-bibliotheek naar een Kotlin-bibliotheek en als gevolg daarvan zijn er enkele wijzigingen waarmee u rekening moet houden.

Voor Java-toepassingen moet u opletten statische methoden en overbelaste functies. In sommige delen van de SDK moet u mogelijk het KAWS COMPANION object om toegang te krijgen tot statische methoden, en het is misschien niet mogelijk om de SDK-managerklasse op dezelfde manier te instantiëren als voorheen.

We hebben geprobeerd ervoor te zorgen dat de verschillen voor de migratie minimaal zijn, maar het wordt aanbevolen dat u de documentatie en voorbeeldcode voor de bijgewerkte Kotlin SDK zorgvuldig doorleest om eventuele wijzigingen in het gebruik te begrijpen. Controleer daarnaast uw bestaande codebase en werk eventuele aanroepen bij naar verouderde of verwijderde methoden om problemen tijdens het migratieproces te voorkomen.

Over het algemeen zou de migratie naar de nieuwe Kotlin SDK eenvoudig moeten zijn. De wijzigingen zijn aangebracht om de functionaliteit en consistentie van de SDK te verbeteren. Het is echter belangrijk om uw codebase na de migratie grondig te testen om er zeker van te zijn dat alles correct werkt.

Van 1.5.7 tot 1.6.0

Werk CMP-ID's bij naar code-ID's voor voortgezet gebruik van de SDK

We brengen enkele wijzigingen aan in de CMP-ID's die worden gebruikt om onze CMP te identificeren. Om ervoor te zorgen dat u onze SDK kunt blijven gebruiken, is het noodzakelijk om de CMP-ID's met het nieuwe Code-ID's die te vinden is in het admin-gedeelte voor de SDK-code.

Hoe werkt u de CMP-ID's bij?

Om de CMP-ID's bij te werken, moet u zich aanmelden bij het beheerdersgedeelte van de Consentmanager en zoek de nieuwe code-ID's (Code ophalen -> Instellingen voor apps (Android/iOS)). Zodra je de nieuwe hebt Code-ID, je kunt de vervangen CMP-ID in uw SDK-code mee

We raden u aan uw SDK-code bij te werken met de nieuwe Code-ID's zo snel mogelijk om ervoor te zorgen dat u ons CMP ononderbroken kunt blijven gebruiken.

Houd er rekening mee dat het einde van de levensduur van de CMP-ID is gepland december 2023. Dit betekent dat de CMP-ID na die datum niet meer wordt ondersteund. Als u vragen of opmerkingen heeft over deze migratie, aarzel dan niet om contact op te nemen met ons ondersteuningsteam voor hulp!

Update naar nieuwe naamgevingsconventies voor interfaces

We hebben enkele wijzigingen aangebracht in onze interfacenaamgevingsconventies om de API van de native SDK's te synchroniseren en voor een beter begrip van het domein. Als gevolg van deze wijzigingen zijn enkele API-handtekeningen gewijzigd en zijn enkele nieuwe methoden geïntroduceerd.

Dit zijn de wijzigingen die zijn aangebracht:

Update Error Callback met CMP Error Types

We introduceren CMP-fouttypen in de fout-callback om meer flexibiliteit te bieden en meer onderscheidend gedrag mogelijk te maken, afhankelijk van het type fout dat optreedt. Met deze update kunt u verschillende soorten fouten effectiever afhandelen, wat ervoor zorgt dat uw gebruikers de best mogelijke ervaring hebben.

Wat zijn CMP-fouttypen?

CMP-fouttypen zijn een reeks fouttypen die zijn geïntroduceerd in de foutcallback. Deze fouttypen worden gebruikt om het type fout te identificeren dat is opgetreden en ze kunnen worden gebruikt om verschillende gedragingen te activeren, afhankelijk van het type fout.

De vier CMP-fouttypen die zijn geïntroduceerd, zijn:

• Netwerkfout
• Time-outFout
• ToestemmingReadWriteError
• ConsentLayerError

Welke invloed heeft deze wijziging op uw code?

Ter ondersteuning van de nieuwe CMP-fouttypen is de handtekening van de fout-callback bijgewerkt. De nieuwe handtekening is:

fun errorOccurred(type: CmpError, message: String)

U moet uw code bijwerken om de nieuwe handtekening te gebruiken en om de verschillende soorten fouten op de juiste manier af te handelen.

Hoe ga je om met verschillende soorten fouten?

Om verschillende soorten fouten af ​​te handelen, kunt u de parameter CmpError gebruiken die wordt doorgegeven aan de foutcallback. Deze parameter bevat het type fout dat is opgetreden, dat u kunt gebruiken om ander gedrag te activeren.

U kunt bijvoorbeeld een NetworkError anders afhandelen dan een ConsentLayerError. U kunt de parameter CmpError gebruiken om het type fout te bepalen en het juiste gedrag te activeren.

Een voorbeeld voor een implementatie kan er als volgt uitzien: 

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

Nieuwe callback voor het identificeren van gebruikersknopgebeurtenissen: 

We hebben een nieuwe callback-functie toegevoegd, OnCmpButtonClickedCallback, die kan worden gebruikt om de interacties van gebruikers met de toestemmingslaag te bepalen door de specifieke knopklikgebeurtenissen vast te leggen. Deze callback helpt ontwikkelaars inzicht te krijgen in gebruikersvoorkeuren en de gebruikerservaring dienovereenkomstig aan te passen.

Een voorbeeld voor een implementatie kan er als volgt uitzien: 

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