[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. Aby zapoznać się z naszą aplikacją demonstracyjną prezentującą przypadki użycia i implementację, która mogłaby służyć jako punkt wyjścia, sprawdź nasze repozytorium z przykładem w Javie i Kotlinie. 

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

Kurs 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

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.

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:

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

SDK oferuje, dla zapewnienia elastyczności, sposób ręcznego wyświetlania warstwy zgody, choć kosztem dwóch odsłon. Przykład: 

// code snippet to manually check the need for consent and manually display the consent layer
// ***********************************************************************
// * ATTENTION: although some users might prefer this                    *
// *            Use Case below instead of the automatic way, it          *
// *            comes with a cost of one page view for the check()       *
// *.           method, and another pageview for the openConsentLayer(), *
// *            so be aware. 											 *
// ***********************************************************************

cmpManager.check({ isConsentRequired ->
  if (isConsentRequired) {
    // Consent is required, handle accordingly
    runOnUiThread {
      // Update UI or show consent dialog
      cmpManager.openConsentLayer()
      }
  } 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

Zachowanie dialogowe

Korzystanie ze strategii fragmentów

<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

Sprawdzanie zgody

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)

Przekazywanie informacji o Zgodzie do innych źródeł

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ń:

Zgoda na import/eksport

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

// Importing consent data if desired
cmpManager.importCmpString("your_base64_encoded_consentString")

// ... Your code here ...

// Exporting consent data
val consentString: String = cmpManager.exportCmpString()

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

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
    }

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