Informacia
Treść

[Android] 0. Przewodnik migracji

Wersja 1.7.33

Przewodnik po migracji do nowego repozytorium SDK

Repozytorium SDK zostało przeniesione do oficjalnego repozytorium Maven. Oto przewodnik krok po kroku, jak zaktualizować projekt, aby korzystał z nowego repozytorium i najnowszej wersji pakietu SDK.

Przed migracją

Krok 1: Dodaj repozytorium Jitpack

Dodaj repozytorium Jitpack do katalogu głównego build.gradle na końcu repozytoriów:

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

Krok 2: Dodaj zależność

Dodaj zależność do pliku build.gradle swojej aplikacji, aby uzyskać najnowszą wersję pakietu SDK:

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

Krok 1: Usuń repozytorium Jitpack

Usuń repozytorium Jitpack z katalogu głównego build.gradle:

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

Krok 2: Dodaj oficjalne repozytorium Maven

Zastąp starą zależność nową zależnością z oficjalnego repozytorium Maven:

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

Teraz Twój projekt został zaktualizowany, aby korzystać z nowego oficjalnego repozytorium Maven i najnowszej wersji SDK (1.7.33). Pamiętaj o zsynchronizowaniu projektu i zaktualizowaniu wszelkich innych konfiguracji lub kodu, na które ta migracja może mieć wpływ.

Od 1.xx do 1.6.3

Należy pamiętać, że aktualizacja do nowej wersji aplikacji nie zawsze przebiega bezproblemowo. W niektórych przypadkach może być konieczne zmodyfikowanie kodu lub zaktualizowanie zależności, aby zapewnić prawidłowe działanie aplikacji.

Zmiany do sprawdzenia Consentlayer

W poprzedniej wersji CMP SDK sprawdzanie warstwy zgody było zintegrowane z główną funkcją konstruktora. W nowej wersji aplikacji oddzieliliśmy check w nowej funkcji o nazwie initialize(). Ta zmiana została wprowadzona w celu poprawy niezawodności i spójności sprawdzania warstwy zgody.

Aby użyć funkcji initialize(), możesz wywołać metodę createInstance() z wymaganymi parametrami i dodać funkcję initialize() do zwróconego obiektu:

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

W tym przykładzie wywołujemy metodę createInstance() w celu zainicjowania warstwy zgody. Funkcja inicjalizacji zażąda consentmanager i określa, czy warstwa zgody musi być wyświetlana, czy nie.

Jeśli wcześniej korzystałeś z automatycznej aktualizacji dla warstwy zgody w swojej aplikacji, musisz zmodyfikować swój kod, aby zamiast tego używać funkcji initialize(). Dzięki temu warstwa zgody będzie sprawdzana spójnie i niezawodnie w nowej wersji aplikacji. Bez funkcji initialize() zostanie utworzona tylko instancja.

Jeśli używasz niestandardowego układu, zwróć uwagę na przekazanie instancji działania podczas inicjalizacji. Aby upewnić się, że fragment zostanie poprawnie dodany do działania. 

Zmiany w wywołaniach zwrotnych

W poprzedniej wersji CMP SDK mieliśmy różne wywołania zwrotne, które były mylące w użyciu. W nowej wersji dostępne są teraz cztery oddzielne funkcje wywołania zwrotnego, które można zaimplementować. Te funkcje wywołania zwrotnego wystarczy raz dodać do instancji i będą dostępne podczas wszystkich interakcji interfejsu API.

Cztery wywołania zwrotne mają następujące nazwy:

  • onOpenCallback: Ta funkcja jest wywoływana, gdy warstwa zgody zostanie pomyślnie otwarta.
  • OnCloseCallback: Ta funkcja jest wywoływana, gdy warstwa zgody jest zamknięta.
  • OnCMPNotOpenedCallback: Ta funkcja jest wywoływana, gdy nie można otworzyć warstwy zgody.
  • OnErrorCallback: Ta funkcja jest wywoływana, gdy podczas interakcji z warstwą zgody wystąpi błąd.

Połączenia OnErrorCallback zostanie wywołana dla wszystkich typowych błędów, zamiast oddzielnych funkcji wywołania zwrotnego błędów używanych w poprzedniej wersji aplikacji.

Aby użyć tych wywołań zwrotnych, możesz je zaimplementować w konstruktorze warstwy zgody w następujący sposób:

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

).
Nowe funkcje API

W poprzedniej wersji zestawu CMP SDK nie było dostępnych funkcji umożliwiających uzyskiwanie informacji o włączonych i wyłączonych dostawcach użytkownika ani o włączaniu i wyłączaniu list dostawców i celów. W nowej wersji aplikacji dodaliśmy kilka nowych funkcji API, które umożliwiają głębszą interakcję z warstwą zgody.

Nowe funkcje API to:

  • getAgreedVendors: Ta funkcja zwraca ciąg zawierający identyfikatory dostawców, na których zgodził się użytkownik.
  • getAgreedVendorList: Ta funkcja zwraca listę identyfikatorów dostawców, których użytkownik zaakceptował.
  • getDisabledVendors: Ta funkcja zwraca listę identyfikatorów dostawców, których użytkownik wyłączył.
  • enableVendorList: Ta funkcja włącza określonych dostawców.
  • disableVendorList: Ta funkcja wyłącza określonych dostawców.
  • enablePurposeList: Ta funkcja umożliwia realizację określonych celów i domyślnie aktualizuje listę dostawców.
  • disablePurposeList: Ta funkcja wyłącza określone cele i domyślnie aktualizuje listę dostawców.
  • rejectAll: Ta funkcja symuluje odrzucenie przez użytkownika wszystkich dostawców i celów. Wymaga OnConsentReceivedCallback funkcja wywołania zwrotnego do obsługi asynchroniczności interfejsu API.
  • acceptAll: Ta funkcja symuluje akceptację przez użytkownika wszystkich dostawców i celów. Wymaga OnConsentReceivedCallback funkcja wywołania zwrotnego do obsługi asynchroniczności interfejsu API.

Połączenia rejectAll i acceptAll funkcje wymagają zapewnienia funkcji wywołania zwrotnego w celu obsługi asynchroniczności interfejsu API. Należy zaimplementować dowolną logikę biznesową, która zależy od wyników tych funkcji wewnątrz funkcji wywołania zwrotnego, aby zapewnić poprawną aktualizację aplikacji.

Zmiany w funkcji importConsent

W poprzedniej wersji zestawu SDK CMP plik importCMPData funkcja została użyta do zaimportowania ciągu zgody cmp do udostępnionych preferencji aplikacji. W nowej wersji aplikacji ta funkcja została zaktualizowana. Ta funkcja zostanie zsynchronizowana z Consentmanager Backend dla lepszej spójności i mniejszej liczby błędów.

Aby zapewnić funkcjonalność zaktualizowanego importCMPData funkcji, zaimplementowano wywołanie zwrotne. To wywołanie zwrotne powiadamia o tym, czy import się powiódł, czy nie. Każda logika biznesowa zależna od wyniku powinna być również zaimplementowana w tym wywołaniu zwrotnym.

Zaktualizowana funkcja ma następującą sygnaturę:

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

Możesz użyć tej funkcji, aby zaimportować pełny ciąg zgody wygenerowany przez ConsentWebView do udostępnionych preferencji Twojego urządzenia. Aby wywołać funkcję należy podać następujące parametry:

  • context: Kontekst aplikacji
  • cmpData: Ciąg zgody na import zakodowany w base64
  • callback: Funkcja wywołania zwrotnego, która odbiera wynik operacji importu

Jeśli import się powiedzie, funkcja wywoła metodę onImportResult metoda wywołania zwrotnego z success parametr ustawiony na true oraz komunikat wskazujący, że import się powiódł. Jeśli import się nie powiedzie, funkcja wywoła metodę onImportResult metoda wywołania zwrotnego z success parametr ustawiony na false oraz komunikat wskazujący, dlaczego import się nie powiódł.

Każda logika biznesowa zależna od wyniku operacji importu powinna zostać zaimplementowana w wywołaniu zwrotnym, aby zapewnić poprawną aktualizację aplikacji.

Zmiany w języku programowania Kotlin

Migracja do nowego zestawu SDK Kotlin wymaga kilku zmian w sposobie korzystania z zestawu SDK. Aplikacja została refaktoryzowana z biblioteki Java do biblioteki Kotlin, w wyniku czego należy wziąć pod uwagę pewne zmiany.

W przypadku aplikacji Java należy zwrócić uwagę metody statyczne i przeciążone funkcje. W niektórych częściach SDK może być konieczne użycie Towarzysz obiektu w celu uzyskania dostępu do metod statycznych i może nie być możliwe utworzenie wystąpienia klasy menedżera SDK w taki sam sposób, jak poprzednio.

Staraliśmy się zapewnić, że różnice w migracji będą minimalne, ale zalecamy uważne przejrzenie dokumentacji i przykładowego kodu dla zaktualizowanego Kotlin SDK, aby zrozumieć wszelkie zmiany w użyciu. Ponadto przejrzyj istniejącą bazę kodu i zaktualizuj wszelkie wywołania przestarzałych lub usuniętych metod, aby uniknąć problemów podczas procesu migracji.

Ogólnie rzecz biorąc, migracja do nowego zestawu SDK Kotlin powinna być prosta. Zmiany zostały wprowadzone w celu poprawy funkcjonalności i spójności zestawu SDK. Jednak ważne jest, aby dokładnie przetestować bazę kodu po migracji, aby upewnić się, że wszystko działa poprawnie.

Od 1.5.7 do 1.6.0
Zaktualizuj identyfikatory CMP do identyfikatorów kodów, aby móc nadal korzystać z pakietu SDK

Wprowadzamy pewne zmiany w identyfikatorach CMP, które służą do identyfikacji naszego CMP. Aby mieć pewność, że możesz nadal korzystać z naszego SDK, konieczna będzie aktualizacja Identyfikatory CMP z nowym Identyfikatory kodów który można znaleźć w obszarze administratora dla kodu SDK.

Jak zaktualizować identyfikatory CMP?

Aby zaktualizować identyfikatory CMP, musisz zalogować się do obszaru administracyjnego dla Consentmanager i znajdź nowe identyfikatory kodów (Uzyskaj kod -> Konfiguracja dla aplikacji (Android/iOS)). Gdy już masz nowe Identyfikator kodu, możesz wymienić Identyfikator CMP w swoim kodzie SDK z nim

SetupCodeId.png

Zalecamy zaktualizowanie kodu SDK o nowy Identyfikatory kodów tak szybko, jak to możliwe, aby mieć pewność, że możesz nadal korzystać z naszego CMP bez przerw.

Należy pamiętać, że planowany jest koniec okresu eksploatacji identyfikatora CMP-ID Grudzień 2023. Oznacza to, że identyfikator CMP-ID nie będzie już obsługiwany po tej dacie. Jeśli masz jakiekolwiek pytania lub wątpliwości dotyczące tej migracji, nie wahaj się skontaktować z naszym zespołem pomocy technicznej w celu uzyskania pomocy!

Aktualizacja do nowych konwencji nazewnictwa interfejsów

Wprowadziliśmy pewne zmiany w naszych konwencjach nazewnictwa interfejsów, aby zsynchronizować interfejs API natywnych zestawów SDK i lepiej zrozumieć domenę. W wyniku tych zmian zmodyfikowano niektóre sygnatury API oraz wprowadzono kilka nowych metod.

Oto wprowadzone zmiany:

Stary podpis API Nowy podpis API
checkAndOpenCmpLayer();

checkAndOpenCmpLayer(appInterface: string);

getLastConsentString();

getConsentstring();

exportCMPData();

exportCmpString();

importCMPData(cmpData: string);

importCmpString(cmpString: string);

getAgreedVendor();

getEnabledVendors();

Zaktualizuj wywołanie zwrotne błędu za pomocą typów błędów CMP

Wprowadzamy typy błędów CMP do wywołania zwrotnego błędu, aby zapewnić większą elastyczność i umożliwić bardziej rozróżnialne zachowanie w zależności od rodzaju występującego błędu. Dzięki tej aktualizacji będziesz w stanie skuteczniej radzić sobie z różnymi typami błędów, co pomoże zapewnić użytkownikom jak najlepsze wrażenia.

Jakie są typy błędów CMP?

Typy błędów CMP to zestaw typów błędów, które zostały wprowadzone do wywołania zwrotnego błędu. Te typy błędów są używane do identyfikowania typu błędu, który wystąpił, i mogą być używane do wyzwalania różnych zachowań w zależności od typu błędu.

Cztery typy błędów CMP, które zostały wprowadzone, to:

  • Błąd sieci
  • Błąd limitu czasu
  • Błąd odczytu i zapisu zgody
  • Błąd warstwy zgody

Jak ta zmiana wpłynie na Twój kod?

W celu obsługi nowych typów błędów CMP zaktualizowano sygnaturę wywołania zwrotnego błędu. Nowy podpis to:

fun errorOccurred(type: CmpError, message: String)

Będziesz musiał zaktualizować swój kod, aby używał nowego podpisu i odpowiednio obsługiwał różne typy błędów.

Jak radzić sobie z różnymi typami błędów?

Aby obsłużyć różne typy błędów, można użyć parametru CmpError, który jest przekazywany do wywołania zwrotnego błędu. Ten parametr będzie zawierał typ błędu, który wystąpił, którego można użyć do wywołania różnych zachowań.

Na przykład możesz obsłużyć NetworkError inaczej niż ConsentLayerError. Możesz użyć parametru CmpError, aby określić typ błędu i wyzwolić odpowiednie zachowanie.

Przykład implementacji może wyglądać następująco: 

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")
                        }
                    }
                }
Nowe wywołanie zwrotne do identyfikowania zdarzeń przycisku użytkownika: 

Dodaliśmy nową funkcję oddzwaniania, OnCmpButtonClickedCallback, które można wykorzystać do określenia interakcji użytkowników z warstwą zgody poprzez przechwytywanie określonych zdarzeń kliknięcia przycisku. To wywołanie zwrotne pomaga programistom uzyskać wgląd w preferencje użytkownika i odpowiednio dostosować środowisko użytkownika.

Przykład implementacji może wyglądać następująco: 

            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")
                        }
                    }
                }
            }
Powrót do góry