[Reaguj natywnie] 1. consentmanager Integracja SDK
Należy pamiętać, że ta wersja pakietu CMP SDK została całkowicie przebudowana od podstaw, dlatego stanowi ona istotna zmiana w stosunku do wersji 2, ponieważ zmieniono nazwy wszystkich metod, zmieniono nazwy sygnatur, a teraz można też skorzystać z wywołań zwrotnych do niemal wszystkich metod. We wszystkich przypadkach, musisz zmodyfikować kod i zaktualizować zależności, aby zapewnić prawidłowe działanie aplikacji mobilnej. Warto również wspomnieć, że w zależności od wersji v2, która została zintegrowana z aplikacją, wszystkie dane zapisane przez poprzednią wersję naszego SDK na urządzeniach użytkowników zostaną usunięte, co zmusi aplikację do ponownie wyświetl warstwę zgody.
Ze względu na charakter React Native jako frameworka oraz ciągłe konflikty żądań i przypadków skrajnych od naszych klientów, oferujemy pomost React Native do bazowych natywnych zestawów SDK jako punkt wyjścia, który stara się spełnić wszystkie żądania w możliwie najszerszym zakresie. Jeśli z jakiegoś powodu potrzebujesz któregokolwiek żądania, zachęcamy do rozwidlenia naszych repozytoriów i dostosowania ich do własnych potrzeb. Oferujemy dwa repozytoria, jedno dla… stara architektura, i jeszcze jeden dla nowa architektura.
Nasz zestaw SDK React Native jest w rzeczywistości mostem do podstawowego zestawu SDK natywnego iOS oraz Android SDK. Aby uzyskać więcej informacji o naszych interfejsach API, sprawdź konkretne wersje platform.
W tym dokumencie znajdziesz ogólne informacje na temat integracji naszego zestawu SDK z Twoim projektem. Aby uzyskać więcej szczegółów, zapoznaj się z naszą dokumentacją referencyjną API. iOS oraz Android.
1. Instalacja
consentmanager SDK to kompleksowe rozwiązanie do zarządzania zgodą użytkownika w aplikacjach mobilnych. Zaprojektowany do obsługi zgodności z GDPR, preferencji prywatności użytkownika i przejrzystości śledzenia reklam, ten SDK zapewnia bezproblemową integrację z platformami iOS i Android. Ponadto oferuje wtyczki/mostki opakowujące dla React Native, Flutter i Unity, dzięki czemu jest wszechstronny w różnych środowiskach programistycznych.
W tym dokumencie opisano procedurę instalacji i funkcje udostępniane naszym klientom tworzącym aplikacje przy użyciu React Native, aby mogli uzyskać dostęp do naszego zestawu SDK CMP do zarządzania zgodami za pośrednictwem naszego mostu React Native Native Bridge. Aby uzyskać więcej szczegółów, zapoznaj się z naszą Dokumentacja API dokumentacja.
1.1 Kroki – opis ogólny
-
Integracja i konfiguracja:
- Zintegruj pakiet SDK ze swoją aplikacją.
- Skonfiguruj ustawienia SDK zgodnie ze swoimi potrzebami.
-
Tworzenie instancji i wyświetlanie warstwy zgody:
- Podczas uruchamiania aplikacji utwórz instancję
CMPManagerklasa. Ta instancja będzie obsługiwać proces wyrażania zgody. - W razie potrzeby zestaw SDK automatycznie wyświetli ekran zgody.
- Podczas uruchamiania aplikacji utwórz instancję
-
Przetwarzanie danych zgody użytkownika:
- Po zebraniu zgód informacje są przechowywane i dostępne do zapytania za pośrednictwem różnych właściwości i metod udostępnianych przez nasz zestaw SDK. Będziesz mieć informacje o odrzuconych lub zaakceptowanych zgodach, dostawcach i celach.
1.2 Przegląd interfejsu API konfiguracji
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 pośrednictwem 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 do NPM (stary oraz nowy łuk) i nasze publiczne repozytoria (pliki tar do bezpośredniego linkowania można znaleźć tutaj stary oraz nowy łuk). Uruchom ten wiersz na swoim 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Łączenie (React Native 0.59 i starsze)
Jeśli używasz React Native 0.59 lub starszej wersji, musisz ręcznie połączyć moduły natywne:
react-native link cm-sdk-react-native-v31.4 Tworzenie instancji i wyświetlanie warstwy zgody
Będziesz musiał skonfigurować informacje CMP za pomocą setUrlConfig metoda, która obsługuje konfigurację CMP, taką jak Code-ID i domyślny język, i setWebViewConfig, co skonfiguruje wygląd WebView, który będzie wyświetlał warstwę zgody. Następnie możesz użyć tej metody. checkAndOpen(false) aby automatycznie pobrać niezbędne dane z naszego serwera i określić, czy ekran zgody ma zostać wyświetlony, czy nie. boolean parametr określa, czy warstwa zgody zostanie otwarta na stronie ustawień (true) co umożliwi użytkownikom dostosowanie swoich wyborów lub wyświetlenie warstwy zgody (false) domyślna strona projektu Twojego CMP.
Należy pamiętać, że funkcjonalności związane z ustaleniem, czy zgoda jest potrzebna, czy nie, a także z wyświetlaniem warstwy zgody, zależą od niezawodnego połączenia sieciowego. Jeżeli nie ma dostępnego połączenia lub mechanizm ponownej próby nie dotrze do naszego serwera, didReceiveError zdarzenie zwróci błąd przekroczenia limitu czasu, i w związku z tym SDK nie będzie w stanie w ogóle określić potrzeby uzyskania zgody, ponieważ nie będzie w ogóle możliwe wyświetlenie warstwy zgody. Upewnij się, że Twoja logika to uwzględnia.
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 zestaw SDK automatycznie wyświetli ekran zgody (baner plików cookie) za pośrednictwem WebView utworzony przez nasz zestaw SDK, który wyświetli warstwę zgody z tekstem i przyciskami zgodnie z konfiguracją CMP (wybraną za pomocą identyfikatora kodu CMP), zbierze dane i zapisze informacje o zgodzie w obszarze NSUserDefaults/UserPreferences urządzenia, aby inne zestawy SDK mogły je odczytać.
2. Przetwarzanie danych za zgodą użytkowników
2.1 Sprawdzanie zgód użytkowników
Nasz zestaw SDK oferuje różne metody sprawdzania i pobierania informacji o zgodzie. Najważniejsza z nich to getUserStatus, jak pokazano w poniższym przykładzie. 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 pełną dokumentacją API podstawowej natywnej metody iOS oraz Android Zestawy SDK.
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 zadzwonić pod numer 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, która została utworzona w poprzednich krokach.
2.3 Importowanie/eksportowanie informacji o zgodzie do innych źródeł
W niektórych przypadkach aplikacja natywna może zawierać widoki webowe w celu wyświetlania informacji, takich jak reklamy lub treści. Aby przesłać informacje o zgodzie z zestawu SDK do widoku webowego i uniknąć duplikowania banerów dotyczących plików cookie, można pobrać ciąg zgody za pomocą exportCMPInfoSpowoduje to wyeksportowanie ciągu zgody wraz ze zgodą i wszystkimi innymi danymi potrzebnymi CMP. Następnie możesz przekazać te informacje do CMP w swoim widoku internetowym, dodając je do adresu URL wywoływanego w widoku internetowym. Aby uzyskać więcej informacji, zapoznaj się z naszą Strona dedykowana w tym przypadku 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 zastępujesz checkAndOpen by importCMPInfo na przykład za pomocą ciągu zgody, który pobrałeś ze strony internetowej.
2.4 Słuchacze zdarzeń
Zestaw SDK udostępnia kilka detektorów zdarzeń, które umożliwiają reagowanie na różne zdarzenia w trakcie procesu uzyskiwania zgody. Te detektory umożliwiają śledzenie interakcji użytkowników, obsługę błędów i synchronizację stanu aplikacji z cyklem życia warstwy zgody.
Wszystkie obiekty nasłuchujące zwracają obiekt subskrypcji, który można wykorzystać do usunięcia obiektu nasłuchującego, gdy nie jest już potrzebny. Aby usunąć obiekt nasłuchujący, należy wywołać metodę .remove() na zwróconej subskrypcji.
Dostępne obiekty nasłuchujące zdarzeń
addConsentListener(callback)
Ten moduł nasłuchujący jest aktywowany, gdy użytkownik wyraża zgodę (akceptując, odrzucając lub dostosowując swoje preferencje).
Parametry:
callback: (consent: string, jsonObject: Object) => voidconsent:Ciąg zgody w formacie IAB TCFjsonObject: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 moduł nasłuchujący jest aktywowany, gdy użytkownikowi wyświetlana jest warstwa zgody.
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 obiekt nasłuchujący jest aktywowany po zamknięciu warstwy zgody, niezależnie od tego, czy użytkownik dokonał wyboru, czy go 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 moduł nasłuchujący jest aktywowany, gdy w trakcie procesu wyrażania zgody wystąpi błąd, na przykład awaria sieci, błędy przekroczenia limitu czasu lub problemy z konfiguracją.
Parametry:
callback: (error: string) => voiderror:Ciąg znaków opisujący błąd, który wystąpił
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 obiekt nasłuchujący jest aktywowany, gdy użytkownik kliknie link w warstwie zgody (taki jak link do polityki prywatności lub warunków korzystania z usługi).
Parametry:
callback: (url: string) => voidurl:Kliknięty adres URL
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 korzystasz ze śledzenia lub analityki w swojej aplikacji, zalecamy zapoznanie się z przewodnikiem Implementacja ATT tutaj.
4. Tworzenie niestandardowego układu
Aby utworzyć niestandardowy widok WKWebView, na przykład zmienić jego położenie lub tło, możesz zmienić 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
Podczas korzystania z naszego zestawu SDK dla systemu iOS może zaistnieć potrzeba debugowania lub analizowania informacji z dziennika w różnych celach. Dzienniki generowane przez nasz zestaw SDK są oznaczone jako „CMP”, co pozwala na łatwe filtrowanie i przeglądanie tylko odpowiednich dzienników. Aby uzyskać więcej informacji, zapoznaj się z w tej sekcji naszej dokumentacji.
6. Ostrzeżenia dotyczące platformy
- Expo nie jest obsługiwane
- AAndroid obecnie ignoruje nadpisania backgroundStyle i customRect/custom pozycja; zawsze wyświetla przyciemnione tło na pełnym ekranie.
- System iOS obsługuje opcje przyciemniania/kolorowania/rozmycia/braku i customRect.
