1. Instalacja

consentmanager SDK to kompleksowe rozwiązanie do zarządzania zgodą użytkownika w aplikacjach mobilnych. Zaprojektowany z myślą o zgodności z RODO, preferencjach użytkowników dotyczących prywatności oraz przejrzystości śledzenia reklam, ten SDK zapewnia płynną integrację z platformami iOS i Android. Dodatkowo oferuje wtyczki/mostki dla React Native, Flutter i Unity, dzięki czemu jest wszechstronny w różnych środowiskach programistycznych.

Niniejszy dokument opisuje procedurę instalacji oraz funkcje udostępniane naszym klientom tworzącym aplikacje w React Native, umożliwiające dostęp do naszego SDK CMP do zarządzania zgodami za pośrednictwem naszego React Native Native Bridge. Więcej szczegółów można znaleźć w naszej dokumentacji API Reference. 

1.1 Etapy – ogólny opis

1. Integracja i konfiguracja:

   • Zintegruj SDK z aplikacją.
   • Skonfiguruj ustawienia SDK zgodnie ze swoimi potrzebami.

2. Tworzenie instancji i wyświetlanie warstwy zgody:

   • Po uruchomieniu aplikacji utwórz instancję klasy CMPManager klasy. Instancja ta będzie obsługiwać proces uzyskiwania zgody.
   • W razie potrzeby SDK automatycznie wyświetli ekran zgody.

3. Przetwarzanie danych dotyczących zgody użytkownika:

   • Po zebraniu zgód informacje są przechowywane i dostępne do wyszukiwania za pomocą różnych właściwości i metod udostępnianych przez nasz SDK. Będziesz mieć informacje o odrzuconych lub zaakceptowanych zgodach, dostawcach i celach.

1.2 API konfiguracji w skrócie

setUrlConfig({ id, domain, language, appName, noHash? = false })

setWebViewConfig({
      position? = fullScreen,
      customRect? (required when position = custom),
      cornerRadius? = 5,
      respectsSafeArea? = true,
      allowsOrientationChanges? = true,
      backgroundStyle? = dimmed(black, 0.5)
})

setATTStatus(status) // iOS only; ATTStatus enum (0–3)

• WebViewPosition: FullScreen | HalfScreenTop | HalfScreenBottom | Custom
• BackgroundStyleType (za pomocą pomocnika BackgroundStyle):
  • dimmed(color?, opacity?)
  • color(color)
  • blur(blurEffectStyle: light | dark | extraLight)
  • none
• ATTStatus: NotDetermined (0), Restricted (1), Denied (2), Authorized (3)
  

1.3 Integracja i konfiguracja

NPM

Opublikowaliśmy nasz most React Native zarówno do NPM (stara i nowa architektura), jak i do naszych publicznych repozytoriów (archiwa do bezpośredniego linkowania można znaleźć dla starej i nowej architektury). Uruchom tę linię w terminalu:

npm install cm-sdk-react-native-v3           // For the old architecture
npm install cm-sdk-react-native-v3-new-arch  // For the new architecture

Łącza (React Native 0.59 i starsze wersje)

Jeśli korzystasz z React Native 0.59 lub starszej wersji, musisz ręcznie połączyć moduły natywne:

react-native link cm-sdk-react-native-v3

1.4 Utworzenie instancji i wyświetlenie warstwy zgody

Musisz skonfigurować informacje CMP za pomocą setUrlConfig , która obsługuje konfigurację CMP, taką jak Code-ID i domyślny język, oraz setWebViewConfig, która skonfiguruje wygląd WebView, w którym wyświetlona zostanie warstwa zgody. Następnie możesz użyć metody checkAndOpen(false) w celu automatycznego pobrania niezbędnych danych z naszego serwera i ustalenia, czy ekran zgody musi zostać wyświetlony, czy nie. boolean określa, czy warstwa zgody zostanie otwarta na stronie ustawień (true), która pozwoli użytkownikom dostosować swoje wybory, czy też warstwa zgody wyświetli (false) domyślną stronę projektową Twojego CMP  

Przykład:

import {
  setUrlConfig,
  setWebViewConfig,
  setATTStatus,
  BackgroundStyle,
  BackgroundStyleType,
  BlurEffectStyle,
  WebViewPosition,
  ATTStatus,
} from 'cm-sdk-react-native-v3';

const HomeScreen: React.FC = () => {
  const [isLoading, setIsLoading] = useState(true);
  const [toastMessage, setToastMessage] = useState<string | null>(null);

  useEffect(() => {
    initializeConsent();
  }, []);

  const initializeConsent = async () => {
    try {
      await setWebViewConfig({
        position: WebViewPosition.HalfScreenBottom,
        backgroundStyle: BackgroundStyle.blur(BlurEffectStyle.Dark),
        cornerRadius: 25,
        respectsSafeArea: true,
        allowsOrientationChanges: true,
        // customRect is required if you pick WebViewPosition.Custom (iOS only;
        // Android falls back)
      });

      await setUrlConfig({
        id: '<your-Code-id>',
        domain: 'delivery.consentmanager.net',
        language: 'EN',
        appName: 'MyApp',
        noHash: true, // optional; defaults to false
      });

      await CmSdkReactNativeV3.checkAndOpen(false);
      console.log('CMPManager initialized and open consent layer opened if necessary');
    } catch (error) {
      console.error('Error initializing consent:', error);
    } finally {
      setIsLoading(false);
    }
};

W tym momencie SDK automatycznie wyświetli ekran zgody (baner dotyczący plików cookie) za pośrednictwem WebView utworzonego przez nasz SDK, który wyświetli warstwę zgody z tekstem i przyciskami zgodnie z konfiguracjami CMP (wybranymi za pomocą identyfikatora Code-ID Twojego CMP), zbierze dane i zapisze informacje o zgodzie w obszarze NSUserDefaults/UserPreferences urządzenia, aby inne SDK mogły je odczytać.

2. Przetwarzanie danych dotyczących zgody użytkowników

2.1 Sprawdzanie zgód użytkowników

Nasz SDK oferuje różne metody sprawdzania i pobierania informacji o zgodzie. Główną z nich jest getUserStatus, jak pokazano w przykładzie poniżej. Aby uzyskać więcej informacji, 

// On the example below retrieved from our Demo App, we have some examples 
// of how to check consents from the user, either accepted or rejected. 

const buttons = [
  {
    title: 'Get User Status',
    onPress: () => handleApiCall(
      CmSdkReactNativeV3.getUserStatus,
      (result) => `User Status: ${JSON.stringify(result).substring(0, 100)}...`,
      'Failed to get user status',
      'getUserStatus'
    ),
  },

Aby uzyskać więcej informacji na temat innych metod, zapoznaj się z naszą pełną dokumentacją API dotyczącą natywnych zestawów SDK dla systemów iOS i Android. 

2.2 Ponowne otwarcie warstwy zgody w celu sprawdzenia wyborów użytkowników

Aby umożliwić użytkownikowi sprawdzenie lub zmianę swoich wyborów, wystarczy po prostu wywołać forceOpen()

const buttons = [
	{
      title: 'Force Open Consent Layer',
      onPress: () => handleApiCall(
        () => CmSdkReactNativeV3.forceOpen(false),
        () => 'Consent Layer opened'
      ),
    },
]

Ta metoda wyświetli warstwę zgody za pośrednictwem tej samej instancji WebView utworzonej w poprzednich krokach. 

2.3 Importowanie/eksportowanie informacji o zgodzie do innych źródeł

W niektórych przypadkach aplikacja natywna może zawierać widoki internetowe w celu wyświetlania informacji, takich jak reklamy lub treści. Aby przesłać informacje o zgodzie z SDK do widoku internetowego i uniknąć powielania banerów dotyczących plików cookie, możesz pobrać ciąg znaków zgody za pomocą exportCMPInfo. Spowoduje to wyeksportowanie ciągu znaków zgody wraz z samą zgodą i wszystkimi dalszymi danymi potrzebnymi CMP. Następnie możesz przekazać te informacje do CMP znajdującego się w twoim widoku internetowym, dodając je do adresu URL wywoływanego w widoku internetowym. Aby uzyskać więcej informacji, sprawdź naszą stronę poświęconą temu przypadkowi użycia. 

Innym przypadkiem użycia jest zgoda między urządzeniami, gdzie importujesz zgodę z innego źródła na urządzenie. W tym przypadku możesz zastąpić checkAndOpen przez importCMPInfo na ciąg znaków zgody pobrany np. ze strony internetowej. 

2.4 Detektyory zdarzeń

SDK udostępnia kilka detektorów zdarzeń, które pozwalają reagować na różne zdarzenia podczas procesu uzyskiwania zgody. Detektory te umożliwiają śledzenie interakcji użytkownika, obsługę błędów oraz synchronizację stanu aplikacji z cyklem życia warstwy zgody.

Wszystkie słuchacze zwracają obiekt subskrypcji, który można wykorzystać do usunięcia słuchacza, gdy nie jest już potrzebny. Aby usunąć słuchacza, wywołaj metodę .remove() na zwróconej subskrypcji.

Dostępne detektory zdarzeń

addConsentListener(callback)

Ten element jest uruchamiany, gdy użytkownik przesyła swoje wybory dotyczące zgody (poprzez akceptację, odrzucenie lub dostosowanie preferencji).

Parametry:

callback: (consent: string, jsonObject: Object) => void
consent: Ciąg tekstowy zgody w formacie IAB TCF
jsonObject: Obiekt JSON zawierający szczegółowe informacje o zgodzie

Przykład:

import { addConsentListener } from 'cm-sdk-react-native-v3';

const consentSubscription = addConsentListener((consent, jsonObject) => {
    console.log('Consent received:', consent);
    console.log('Consent details:', jsonObject);
    // Handle the consent data in your app
});

// To remove the listener later:
// consentSubscription.remove();

addShowConsentLayerListener(callback)
Ten element jest uruchamiany, gdy użytkownikowi wyświetla się okienko z prośbą o zgodę.

Parametry:

callback: () => void

Przykład:

import { addShowConsentLayerListener } from 'cm-sdk-react-native-v3';

const showSubscription = addShowConsentLayerListener(() => {
    console.log('Consent layer is now visible');
    // Pause analytics or other tracking activities
});

addCloseConsentLayerListener(callback)

Ten listener jest uruchamiany po zamknięciu okienka zgody, niezależnie od tego, czy użytkownik dokonał wyboru, czy je odrzucił.

Parametry:

callback: () => void

Przykład:

import { addCloseConsentLayerListener } from 'cm-sdk-react-native-v3';

const closeSubscription = addCloseConsentLayerListener(() => {
    console.log('Consent layer has been closed');
    // Resume normal app flow
});

addErrorListener(callback)

Ten słuchacz jest uruchamiany, gdy podczas procesu uzyskiwania zgody wystąpi błąd, taki jak awaria sieci, błąd przekroczenia limitu czasu lub problem z konfiguracją.

Parametry:

callback: (error: string) => void
error: Ciąg znaków opisujący wystąpiony błąd

Przykład:

import { addErrorListener } from 'cm-sdk-react-native-v3';

const errorSubscription = addErrorListener((error) => {
    console.error('CMP Error:', error);
    // Handle the error appropriately in your app
    // For example, show a fallback UI or retry logic
});

addClickLinkListener(callback)

Ten element jest uruchamiany, gdy użytkownik kliknie link w warstwie zgody (np. link do polityki prywatności lub warunków korzystania z usługi).

Parametry:

callback: (url: string) => void
url: Adres URL, który został kliknięty

Przykład:

import { addClickLinkListener } from 'cm-sdk-react-native-v3';

const linkSubscription = addClickLinkListener((url) => {
    console.log('User clicked link:', url);
    // Optionally handle the link in a custom way
    // For example, open in an in-app browser
});

3. Integracja z Apple Tracking Transparency (ATT)

Jeśli w swojej aplikacji korzystasz z narzędzi do śledzenia lub analityki, zalecamy zapoznanie się z przewodnikiem dotyczącym wdrażania ATT, dostępnym tutaj.

4. Tworzenie niestandardowego układu

Aby stworzyć spersonalizowany widok WKWebView, na przykład zmieniając jego położenie lub tło, możesz zmodyfikować konfigurację przekazaną do obiektu ConsentLayerUIConfig w następujący sposób:

ConsentLayerUIConfig(
    position: .halfScreenTop,
    backgroundStyle: .dimmed(.grey, 0.75),
    cornerRadius: 20,
    respectsSafeArea: false,
    allowsOrientationChanges: true)

5. Logowanie

Korzystając z naszego SDK dla systemu iOS, możesz potrzebować debugowania lub analizy informacji z logów w różnych celach. Logi generowane przez nasze SDK są oznaczone tagiem „CMP”, co pozwala łatwo filtrować i wyświetlać tylko te logi, które są istotne. Więcej informacji znajdziesz w tej sekcji naszej dokumentacji.

6. Uwagi dotyczące platformy

• Expo nie jest obsługiwane
• Android obecnie ignoruje nadpisania backgroundStyle oraz customRect/custom position; zawsze wyświetla przyciemnione tło na całym ekranie.
• iOS obsługuje opcje dimmed/color/blur/none oraz customRect.