Informacia
Treść

[Androida] 1. consentmanager Integracja SDK

W tym dokumencie znajdziesz ogólne informacje na temat integracji naszego SDK z Twoim projektem. Więcej szczegółów znajdziesz w naszym Dokumentacja API dokumentacja.

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

1. Instalacja

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.

Kroki - wysoki poziom

    1. Integracja i konfiguracja:

      • Zintegruj pakiet SDK ze swoją aplikacją.
      • Skonfiguruj ustawienia SDK zgodnie ze swoimi potrzebami.
    2. Tworzenie instancji:

      • Podczas uruchamiania aplikacji utwórz instancję CMPConsentTool klasa. Ta instancja będzie obsługiwać proces wyrażania zgody.
    3. Inicjalizacja SDK:
      • Gdy instancja będzie gotowa, SDK automatycznie pobierze niezbędne informacje z pliku consentmanager serwerów w celu przygotowania ich do działania.
    4. Wyświetlanie ekranu zgody:

      • W razie potrzeby pakiet SDK automatycznie wyświetli ekran zgody CMPConsentTool instancja jest tworzona.
    5. Przetwarzanie danych osobowych:

      • Po zebraniu zgód informacje są przechowywane i można je przeglądać za pomocą różnych właściwości i metod udostępnianych przez nasz pakiet SDK. Będziesz mieć informacje o odrzuconych lub zaakceptowanych zgodach, dostawcach, celach itp.

    Wykonując te kroki, masz pewność, że Twoja aplikacja jest zgodna z wymogami dotyczącymi zgody oraz że zgody użytkowników są odpowiednio zarządzane i przechowywane.

Consent Manager Diagram sekwencji zestawu SDK dostawcy

Aby zilustrować powyższe kroki, sprawdźmy na poniższym diagramie trzy możliwe przepływy sekwencji SDK. 

1. Podczas tworzenia instancji przy użyciu zainicjować funkcji, istnieją dwa możliwe wyniki. Pierwsza ma miejsce, gdy interfejs API zgody informuje zestaw SDK, że CMP nie zostanie otwarty, co powoduje wyzwolenie OnCmpNotOpenedWywołanie zwrotne. Drugim rezultatem jest otwarcie warstwy zgody, co pozwala użytkownikowi na interakcję z nią, a to wyzwala OnOpenCallback. Po wyrażeniu przez użytkownika zgody i przetworzeniu zgody, OnCmpCloseOddzwonienie nazywa się.

Należy pamiętać, że Przy oddzwonieniu po błędzie jest reprezentowany przez czerwone przerywane linie strzałek, aby podać przykłady błędów, które mogą wystąpić podczas procesu.

Zainicjuj-Cmp-Sequence-Diagram.png

2. Tworzenie instancji i wywoływanie otwórz i sprawdź zgodę funkcje doprowadzą do podobnego procesu. Różnica polega na tym, że oddzielając tworzenie instancji od sprawdzania API zgody, zyskujesz możliwość dodawania logiki biznesowej i interakcji z API bibliotek.

3. Tworzenie instancji i wywoływanie Otwórz warstwę funkcja otworzy warstwę bez sprawdzania pliku consentmanager, jeśli to konieczne. Jeśli jest już wyrażona zgoda, opcje i ustawienia zostaną pokazane użytkownikowi. Przebieg procesu będzie wyglądał następująco:

openlayer-Cmp-Schemat-Sekwencji-.png

Więcej informacji na temat naszego przeglądu wersji pakietu SDK i dziennika zmian można znaleźć w artykule pod tym linkiem.

Dodawanie zależności poprzez 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'
}

I

Dodawanie zależności poprzez Maven

Dodaj zależność do pliku build.gradle aplikacji. Aby zawsze otrzymywać najnowszą wersję w Maven, możesz użyć różnych metod, aby odrzucić zakres wersji. Aby sprawdzić dostępne wersje pakietu SDK, prosimy sprawdzić pod tym linkiem. Więcej informacji można znaleźć w artykule tutaj.

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

2. Inicjowanie pakietu SDK

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

Inicjowanie narzędzia ConsentTool — automatycznie

W ramach startu aplikacji (zwykle zwykły override onCreate() funkcja) , musisz utworzyć instancję klasy CMPConsentTool. Plik initialize() funkcja automatycznie pobierze niezbędne dane z naszego serwera i określi, czy należy wyświetlić ekran zgody, czy nie. Jeśli tak, SDK automatycznie wyświetli w tym momencie ekran zgody, zbierze dane i przekaże je aplikacji. Instancję można następnie wykorzystać w celu pobrania szczegółów zgody z SDK w celu wykorzystania jej w aplikacji. Przykład inicjalizacji z wykorzystaniem automatycznego zachowania initialize() metoda:

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

// 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);
        cmpManager.initialize(this)
    }
}

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.).

Inicjowanie narzędzia ConsentTool — ręcznie

Ze względu na elastyczność pakiet SDK oferuje sposób ręcznego wyświetlania warstwy zgody, jak pokazano poniżej: 

        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. W poniższej tabeli możesz sprawdzić zależności pomiędzy parametrami isFocusable i isOutsideTouchable

Zachowanie wyskakującego okienka
Parametr isFocusable = true isFocusable = false
isOutsideTouchable =  true Odrzuca kontakt z zewnątrz. Może uzyskać fokus dla zdarzeń wejściowych. Odrzuca kontakt z zewnątrz. Nie uzyskuje ostrości ani nie przechwytuje danych wejściowych z klawiatury.
isOutsideTouchable = false Nie odrzuca przy dotyku z zewnątrz. Potrafi uzyskać fokus i przechwycić zdarzenia wejściowe. Nie odrzuca przy dotyku z zewnątrz. Nie uzyskuje ostrości ani nie przechwytuje danych wejściowych z klawiatury.

 

 

 

Zachowanie dialogowe
Parametr isFocusable = true isFocusable = false
isOutsideTouchable =  true Odrzuca przy dotyku zewnętrznym (setCanceledOnTouchOutside(true)). Domyślnie można zaznaczyć okno dialogowe. Okno dialogowe nie jest zamykane po dotknięciu z zewnątrz i może nie zachowywać się zgodnie z oczekiwaniami, ponieważ okna dialogowe zazwyczaj można ustawić jako aktywne.
isOutsideTouchable = false Nie odrzuca przy dotyku zewnętrznym (setCanceledOnTouchOutside(false)). Okno dialogowe pozostaje aktywne i może przechwytywać zdarzenia wejściowe. Okno dialogowe nie jest odrzucane pod wpływem zewnętrznego dotyku i może nie zachowywać się zgodnie z oczekiwaniami ze względu na brak możliwości skupienia.
Korzystanie ze strategii fragmentów
R.id.cmpContainer to układ ramki, który mógłby wyglądać tak w układzie xml aktywności w układzie/{twoja_aktywność}.xml

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

3. Korzystanie z SDK

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

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

Obie metody hasPurposeConsent i hasVendorConsent mają dwa parametry, jeden wymaga i jeden jest opcjonalny:

  • id - Ciąg znaków dostawcy lub identyfikatora celu. Należy pamiętać, że identyfikatory dostawców mogą mieć różne formaty („123”, „s123” i „c123”). Sprawdź ponownie za pomocą Menu > Sprzedawcy i Menu > Cele w telefonie consentmanager konta.
  • isIABVendor / isIABPurpose (Opcjonalnie) — jeśli dostawca lub cel jest dostawcą/celem zgodnym ze standardem IAB TCF, należy ustawić wartość „prawda” lub „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ć openConsentLayer():

cmpManager?.openConsentLayer(context)

W niektórych przypadkach aplikacja natywna może zawierać widoki internetowe w celu wyświetlania określonych rzeczy, np. treści reklamowych lub treści. W celu przesłania informacji o zgodzie z SDK do webview należy skorzystać 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ń:

Imię

Występuje

 

OnOpenCallback

Odbiornik zdarzenia po otwarciu CMP

OnCMPZamknijOddzwoń

Odbiornik zdarzenia, gdy CMP jest zamknięty

OnCMPNotOpenedOddzwonienie

Odbiornik zdarzenia, gdy nie trzeba otwierać CMP

Przy oddzwonieniu po błędzie

Listener for Event, gdy wystąpi błąd w procesie zarządzania zgodą.

OnButtonClickedOddzwonienie

Odbiornik zdarzenia ButtonEvent

Zgoda na import/eksport

Aby zaimportować lub wyeksportować zgodę możesz skorzystać z funkcji exportCMPData() i importCMPData(). Sprawdź poniższy przykład: 

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

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
    }

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

 

Powrót do góry