[Androida] 1. consentmanager Integracja SDK

Połączenia consentmanager SDK dla aplikacji na Androida implementuje i zapewnia funkcjonalność informowania użytkownika o ochronie danych oraz pytania i zbierania zgody od użytkownika. Umożliwia programistom aplikacji łatwą integrację consentmanager usługi do swojej aplikacji.

Jak to działa?

1. Zintegruj SDK z aplikacją i skonfiguruj ustawienia SDK
2. Gdy SDK zostanie zintegrowany z aplikacją, SDK udostępni funkcje dla programisty aplikacji w celu pobrania danych dotyczących zgody
3. Gdy tylko aplikacja się uruchomi, SDK automatycznie pobierze informacje z consentmanager serwery w celu przygotowania SDK do jego użycia.
4. Zaleca się, aby przy starcie aplikacji tworzyła instancję klasy CMPConsentTool. Po utworzeniu SDK automatycznie wyświetli ekran zgody, jeśli to konieczne.
5. Gdy aplikacja chce przetwarzać dane osobowe, powinna „zapytać” SDK, czy została wyrażona zgoda na konkretny cel i dostawcę.

Instalacja

Od wersji 1.7.0 repozytorium SDK zostało przeniesione do oficjalnego repozytorium Maven. Można znaleźć Przewodnik migracji tutaj

Znajdź kompatybilne natywne wersje SDK tutaj.

Gradle

Dodaj zależność do pliku build.gradle aplikacji. (Aby zawsze uzyskać najnowszą wersję, użyj symbolu +, aby uzyskać najnowsze aktualizacje. Możesz na przykład zawsze uzyskać najnowsze wersje w przypadku mniejszych aktualizacji do 1.x.+)

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

Maven

Dodaj zależność do pliku build.gradle aplikacji. (Aby zawsze uzyskać najnowszą wersję w maven, możesz użyć różnych metod, aby odrzucić zakres wersji. Możesz je sprawdzić tutaj )

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

Korzystanie z biblioteki

Uprawnienia

Ten pakiet SDK wymaga następujących uprawnień, upewnij się, że dodałeś je do pliku AndroidManifest.xml:

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

Zainicjuj narzędzie zgody

Za pomocą aplikacji startowej (zazwyczaj funkcji viewDidAppear) musisz utworzyć instancję klasy CMPConsentTool. Spowoduje to automatyczne pobranie niezbędnych danych z naszego serwera i określenie, czy ekran akceptacji ma być wyświetlany, czy nie. Jeśli tak, SDK automatycznie wyświetli w tym momencie ekran zgody, zbierze dane i przekaże je do aplikacji. Instancję można następnie wykorzystać w celu uzyskania szczegółów zgody z SDK w celu wykorzystania jej w aplikacji.

Aby zainicjować ConsentTool, przejdź do wybranej klasy i utwórz instancję CMPConsentTool, jak pokazano poniżej:

class CmpDemoActivity : FragmentActivity() {

    private lateinit var cmpManager: CmpManager

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val config = CmpConfig.apply {
            id ="yourid"
            domain = ConsentActivity.CMP_DOMAIN
            appName = ConsentActivity.CMP_APP_NAME
            language = ConsentActivity.LANG
        }
        cmpManager = CmpManager.createInstance(this, config)
        cmpManager.initialize(this)
    }

// Java example instantiation: 

    CmpManager cmpManager = null;
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        CmpConfig cmpConfig = CmpConfig.INSTANCE;
        cmpConfig.setId("YourId");
        cmpConfig.setDomain("delivery.consentmanager.net");
        cmpConfig.setAppName("YourAppName");
        cmpConfig.setLanguage("EN");
        cmpConfig.setTimeout(4000);
        cmpManager = CmpManager.createInstance(this, cmpConfig);
      
    }

// ... open layer and asking for purpose:

        cmpManager.openConsentLayer(getApplication());
        if (cmpManager.hasPurposeConsent("PURPOSE_ID")) {
            Log.d(TAG, "has purpose");
        }

Aby utworzyć instancję CMPConsentTool należy ją skonfigurować. Będziesz musiał podać CODE-ID, domenę serwera, nazwę aplikacji i język. CODE-ID i domenę serwera można znaleźć w pliku consentmanager konto pod Menu > Pobierz kod. Nazwy aplikacji można użyć do rozróżnienia różnych aplikacji w consentmanager raportowanie. Jako język możesz użyć pustego ciągu ("") do automatycznego wykrywania lub dwuliterowego kodu języka ("EN", "DE", "FR" itd.).

Wartości konfiguracyjne można wstawiać na różne sposoby:

a) Konfiguracja SDK poprzez CmpConfig

Dodaj następujące wiersze do swojego kodu:

val config = CmpConfig.apply { 
            serverDomain = CMP_DOMAIN
            appName = CMP_APP_NAME
            language = LANG
            id = CODE_ID
        }
cmpManager = CmpManager.createInstance(this, config)

b) Konfiguracja zestawu SDK za pomocą metody createInstance()

Dodaj następujący wiersz do swojego kodu:

        cmpManager =
            CmpManager.createInstance(
                this,
                config.id,
                config.domain,
                config.appName,
                config.language
            )

Inicjowanie i otwieranie warstwy zgody

Aby sprawdzić, czy użytkownik musi wyrazić zgodę i otworzyć warstwę zgody, dostępne są różne opcje. 

Przez Zainicjuj połączenie

Połączenia initialize Funkcja ma na celu skonfigurowanie pakietu SDK CMP w kontekście aplikacji oraz automatyczne sprawdzanie i otwieranie warstwy zgody, jeśli jest to wymagane. The initialize można powiązać z tworzeniem instancji

cmpManager = CmpManager.createInstance(this, config).initialize(this)

Przez połączenie CheckAndOpen

Podobny jak initialize funkcja CheckAndOpenLayer otworzy warstwę zgody, jeśli jest to wymagane. 

 cmpManager.checkAndOpenConsentLayer(this)

Ręcznie

Połączenia check Funkcja oferuje ręczne podejście do ustalenia, czy wymagana jest zgoda użytkownika. Pozwala na mechanizm wywołania zwrotnego i opcjonalny mechanizm pamięci podręcznej w celu zmniejszenia żądań sieciowych.

        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)

Tworzenie niestandardowego układu

Aby utworzyć niestandardowy układ, możesz użyć CmpUIConfig klasa z różnymi opcjami stylizacji. Ta klasa oferuje również kilka gotowych układów, takich jak 

• skonfigurujHalfScreenBottom
• skonfigurujHalfScreenTop
• skonfigurujCenterScreen
• skonfigurujSmallCenterScreen
• skonfiguruj duży górny ekran
• skonfiguruj duży dolny ekran

Do tworzenia niestandardowego układu CMP SDK oferuje również różne strategie:

• Okno dialogowe
• Wyskakujące okno
• Fragment

Możesz zmienić strategię, ustawiając parametr UIConfig: 

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

Zalecamy użycie okna wyskakującego, które jest również ustawione jako domyślne od wersji 2.3.0

O tym zadecydują dwa ważne parametry Popup i dialog zachowanie: 

Zachowanie wyskakującego okienka

Zachowanie dialogowe

Przykład fragmentu:

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

Wewnętrzne linki do aplikacji i biała lista domen

Aby zaimplementować funkcję, w której określone domeny znajdują się na białej liście i gdy są otwierane w ramach platformy zgody (CMP) WebView, nie są otwierane w zewnętrznej przeglądarce, takiej jak Chrome, ale w samym WebView, możesz zaimplementować mechanizm wywołania zwrotnego w celu wykonywania niestandardowych działań w oparciu o domeny, na przykład otwarcie działania w systemie Android.

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

Korzystanie z SDK

Sprawdź zgodę

Aby sprawdzić, czy sprzedawca lub cel mają zgodę, możesz skorzystać z dwóch metod:

cmpManager?.hasPurposeConsent(purposeTextState.value)
cmpManager?.hasVendorConsent(vendorTextState.value)                             

Obie metody hasPurposeConsent i hasVendorConsent wymagają dwóch parametrów:

• id — ciąg identyfikatora dostawcy lub celu. Należy pamiętać, że identyfikatory dostawców mogą mieć różne formaty („123”, „s123” i „c123”), sprawdź dokładnie za pomocą Menu > Sprzedawcy i Menu > Cele w telefonie consentmanager konta.
• isIABVendor / isIABPurpose — jeśli dostawca lub cel jest dostawcą/celem zgodnym ze standardem IAB TCF, należy ustawić wartość prawda, w przeciwnym razie fałsz.

Pamiętaj: wszyscy dostawcy, którzy nie należą do IAB, mają identyfikatory zaczynające się od „s” lub „c” (np. „s123”); dostawcy należący do IAB mają identyfikatory, które nie zaczynają się od „s” lub „c”.

Ponowne otwieranie ekranu zgody

Aby umożliwić użytkownikowi zmianę wyborów, wystarczy zadzwonić openCmpConsentToolView():

cmpManager?.openConsentLayer(context)

Przekazywanie informacji o Zgodzie do innych źródeł

W niektórych przypadkach natywna aplikacja może zawierać widoki internetowe w celu wyświetlania pewnych rzeczy, takich jak reklamy lub treści. W celu przekazania informacji o zgodzie z SDK do webview prosimy o skorzystanie z funkcji:

String consentData = cmpConsentTool?.exportCmpString();

Spowoduje to wyeksportowanie informacji o zgodzie i wszystkich dalszych danych wymaganych przez CMP. Następnie możesz przekazać te informacje do CMP w widoku sieciowym, dodając je do adresu URL wywoływanego w widoku sieciowym:

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

Niestandardowe odbiorniki zdarzeń

Aby dodać dodatkową logikę procesu, możesz skorzystać z detektorów zdarzeń. Dostępne są następujące detektory zdarzeń:

Zgoda na import/eksport

Aby zaimportować lub wyeksportować zgodę możesz skorzystać z funkcji exportCMPData (kontekst kontekstu) i importCMPData (kontekst kontekstu, ciąg cmpData). Sprawdź poniższy przykład: 

// Importing consent data if you like
                    cmpManager?.importCmpString(
                        "yourConsentString"
                    ) { _, message ->
                        coroutineScope.launch {
                            snackbarHostState.showSnackbar(
                                message = message,
                                actionLabel = "Action",
                                duration = SnackbarDuration.Short
                            )
                        }
                    }

// Exporting Consent data 
String consentString = cmpManager.exportCmpString();

ZgodaString, którą musisz przekazać, powinna być zakodowana w base64.

Diagram sekwencji CMP SDK

Logowanie

Podczas korzystania z naszego pakietu SDK dla systemu Android może zaistnieć potrzeba debugowania lub analizowania informacji z dziennika do różnych celów. Logi generowane przez nasz SDK są oznaczone tagiem „CMP”, co pozwala na łatwe filtrowanie i przeglądanie tylko odpowiednich logów. Ten przewodnik zawiera instrukcje krok po kroku dotyczące uzyskiwania dostępu do tych dzienników za pomocą Logcat w Android Studio.

Wyszukaj tag: w pasku wyszukiwania nad wyciągami dziennika wpisz CMP aby odfiltrować logi oznaczone "CMP".

Opcjonalnie: Włącz tryb debugowania

In CMPConfig, ustaw isDebugMode = true.

val config = CmpConfig.apply {
    // ... other settings
    isDebugMode = true
}

• Umożliwia bardziej szczegółowe dzienniki oznaczone tagiem „CMP”.
• Przydatne do debugowania i analizy.

Rozwiązywanie problemów

Nie znaleziono klasy lub wyjątek NoSuchMethodException:

ProGuard może czasami zaciemniać nazwy klas lub usuwać metody, do których odwołują się dynamicznie poprzez odbicie. Aby to naprawić, musisz określić klasy i metody, które powinny pozostać nienaruszone w pliku konfiguracyjnym ProGuard za pomocą -keep Dyrektywa.

Przykładowa konfiguracja ProGuarda w celu zachowania określonej klasy i jej metod:

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