[ReactNatief] 1. consentmanager SDK-integratie
Houd er rekening mee dat deze versie van de CMP SDK volledig opnieuw is opgebouwd en daarom een belangrijke ingrijpende verandering ten opzichte van v2, aangezien alle methoden een nieuwe naam kregen, evenals de handtekeningen, en nu callbacks voor bijna alle methoden worden aangeboden. In alle gevallen, moet u uw code aanpassen en uw afhankelijkheden bijwerken om ervoor te zorgen dat uw mobiele app naar behoren werkt. Daarnaast is het belangrijk om te vermelden dat, afhankelijk van de versie van v2 die in uw app is geïntegreerd, alle gegevens die door de vorige versie van onze SDK op de apparaten van de gebruikers zijn opgeslagen, worden gewist, wat de app zal dwingen om de toestemmingslaag opnieuw weergeven.
Vanwege de aard van React Native als framework en de constante conflicterende verzoeken en edge cases van onze klanten, bieden we de React Native-brug naar de onderliggende native SDK's aan als uitgangspunt. Deze brug probeert alle verzoeken zo volledig mogelijk te vervullen. Mocht u om welke reden dan ook een verzoek nodig hebben, dan raden we u aan om onze repositories te forken en aan te passen aan uw eigen behoeften. We bieden twee repositories aan, één voor de oude architectuur, en nog een voor de nieuwe architectuur.
Onze React Native SDK is in feite een brug naar de onderliggende native iOS en Android SDK's. Voor meer informatie over onze API's kunt u de specifieke platformversies raadplegen.
In dit document vindt u algemene informatie over hoe u onze SDK in uw project kunt integreren. Raadpleeg voor meer informatie onze API-referentiedocumentatie. iOS en Android.
1. Installatie
consentmanager SDK is een uitgebreide oplossing voor het beheren van gebruikerstoestemming in mobiele applicaties. Deze SDK is ontworpen om GDPR-naleving, gebruikersprivacyvoorkeuren en transparantie bij het volgen van advertenties te verwerken en biedt een naadloze integratie voor iOS- en Android-platforms. Daarnaast biedt het wrapper-plug-ins/bruggen voor React Native, Flutter en Unity, waardoor het veelzijdig is in verschillende ontwikkelomgevingen.
Dit document beschrijft de installatieprocedure en functies die beschikbaar worden gesteld aan onze klanten die apps ontwikkelen met React Native om toegang te krijgen tot onze toestemmingsbeheer CMP SDK via onze React Native Native BridgeVoor meer informatie verwijzen wij u naar onze API-referentie documentatie.
1.1 Stappen - Beschrijving op hoog niveau
-
Integratie en configuratie:
- Integreer de SDK in uw app.
- Configureer de SDK-instellingen volgens uw behoeften.
-
Een instantie maken en de toestemmingslaag weergeven:
- Maak bij het opstarten van de app een exemplaar van het
CMPManagerklas. Deze instantie zal het toestemmingsproces afhandelen. - De SDK geeft indien nodig automatisch het toestemmingsscherm weer.
- Maak bij het opstarten van de app een exemplaar van het
-
Verwerking van toestemmingsgegevens van gebruikers:
- Zodra toestemmingen zijn verzameld, wordt informatie opgeslagen en is deze beschikbaar voor query's via verschillende eigenschappen en methoden die door onze SDK worden blootgesteld. U krijgt informatie over afgewezen of geaccepteerde toestemmingen, leveranciers en doeleinden.
1.2 Configuratie-API in één oogopslag
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(via BackgroundStyle helper):dimmed(color?, opacity?)color(color)blur(blurEffectStyle: light | dark | extraLight)none
ATTStatus: NotDetermined (0), Restricted (1), Denied (2), Authorized (3)
1.3 Integratie en configuratie
NPM
We hebben onze React Native-brug naar zowel NPM (oud en nieuwe boog) en onze openbare repositories (tarballs voor directe koppeling zijn te vinden voor de oud en nieuwe boog). Voer deze regel uit op uw terminal:
npm install cm-sdk-react-native-v3 // For the old architecture
npm install cm-sdk-react-native-v3-new-arch // For the new architectureKoppelen (React Native 0.59 en lager)
Als u React Native 0.59 of lager gebruikt, moet u de native modules handmatig koppelen:
react-native link cm-sdk-react-native-v31.4 Een instantie maken en de toestemmingslaag weergeven
U moet uw CMP-informatie instellen via de setUrlConfig methode, die uw CMP-configuratie afhandelt, zoals Code-ID en standaardtaal, en setWebViewConfig, Hiermee configureert u het uiterlijk van de webweergave die de toestemmingslaag weergeeft. Daarna bent u klaar om de methode te gebruiken. checkAndOpen(false) om automatisch de benodigde gegevens van onze server op te halen en te bepalen of het toestemmingsscherm moet worden weergegeven of niet. De boolean parameter bepaalt of de toestemmingslaag wordt geopend op de instellingenpagina (true) waarmee gebruikers hun keuzes kunnen aanpassen of als de toestemmingslaag wordt weergegeven (false) de standaardontwerppagina van uw CMP.
Houd er rekening mee dat de functionaliteiten met betrekking tot het bepalen of toestemming nodig is of niet, evenals de weergave van de toestemmingslaag, zijn afhankelijk van een betrouwbare netwerkverbinding. Als er geen verbinding beschikbaar is of als het mechanisme voor opnieuw proberen onze server niet bereikt, didReceiveError gebeurtenis zal een time-outfout retourneren, en dus zal de SDK totaal niet in staat zijn om de noodzaak van toestemming te bepalen, omdat de toestemmingslaag dan helemaal niet kan worden weergegeven. Zorg ervoor dat uw logica hier rekening mee houdt.
Voorbeeld:
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);
}
};De SDK zal op dit punt automatisch het toestemmingsscherm (cookiebanner) weergeven via een WebView gemaakt door onze SDK, die de toestemmingslaag weergeeft met de tekst en knoppen volgens uw CMP-configuraties (gekozen via de Code-ID van uw CMP), de gegevens verzamelt en de toestemmingsinformatie opslaat in het NSUserDefaults/UserPreferences-gebied van het apparaat, zodat de andere SDK's deze kunnen lezen.
2. Verwerking van toestemmingsgegevens van gebruikers
2.1 Controle van de toestemmingen van gebruikers
Onze SDK biedt verschillende methoden om toestemmingsinformatie te controleren en op te halen. De belangrijkste is: getUserStatus, zoals weergegeven in het onderstaande voorbeeld. Voor meer informatie,
// 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'
),
},Voor meer informatie over de andere methoden verwijzen wij u naar onze volledige API-documentatie van de onderliggende native iOS en Android SDK's.
2.2 De toestemmingslaag opnieuw openen om de keuzes van de gebruikers te controleren
Om de gebruiker toe te staan zijn keuzes te verifiëren of te wijzigen, kunt u eenvoudig bellen forceOpen()
const buttons = [
{
title: 'Force Open Consent Layer',
onPress: () => handleApiCall(
() => CmSdkReactNativeV3.forceOpen(false),
() => 'Consent Layer opened'
),
},
]Met deze methode wordt de toestemmingslaag weergegeven via hetzelfde WebView-exemplaar dat in de vorige stappen is gemaakt.
2.3 Toestemmingsinformatie importeren/exporteren naar andere bronnen
In sommige gevallen kan een native app webviews bevatten om informatie weer te geven, zoals advertenties of content. Om de toestemmingsinformatie van de SDK naar de webview te verzenden en dubbele cookiebanners te voorkomen, kunt u de toestemmingsstring ophalen met exportCMPInfoHiermee wordt de toestemmingsstring met de toestemming en alle verdere gegevens die de CMP nodig heeft, geëxporteerd. U kunt deze informatie vervolgens doorgeven aan de CMP in uw webview door deze toe te voegen aan de URL die in de webview wordt aangeroepen. Raadpleeg onze speciale pagina voor dit gebruiksvoorbeeld.
Een ander gebruiksvoorbeeld is de toestemming voor meerdere apparaten, waarbij u toestemming van een andere bron naar het apparaat importeert. In dit geval vervangt u checkAndOpen by importCMPInfo bijvoorbeeld met de toestemmingsstring die u van de website hebt opgehaald.
2.4 Gebeurtenisluisteraars
De SDK biedt verschillende event listeners waarmee u kunt reageren op verschillende gebeurtenissen tijdens de toestemmingsstroom. Met deze listeners kunt u gebruikersinteracties volgen, fouten afhandelen en de status van uw app synchroniseren met de levenscyclus van de toestemmingslaag.
Alle listeners retourneren een abonnementsobject dat kan worden gebruikt om de listener te verwijderen wanneer deze niet langer nodig is. Om een listener te verwijderen, roept u .remove() aan op het geretourneerde abonnement.
Beschikbare gebeurtenisluisteraars
addConsentListener(callback)
Deze listener wordt geactiveerd wanneer de gebruiker zijn of haar toestemmingskeuzes indient (door de toestemming te accepteren, af te wijzen of door de voorkeuren aan te passen).
parameters:
callback: (consent: string, jsonObject: Object) => voidconsent: De toestemmingsstring in IAB TCF-formaatjsonObject: Een JSON-object met gedetailleerde toestemmingsinformatie
Voorbeeld:
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)
Deze listener wordt geactiveerd wanneer de toestemmingslaag aan de gebruiker wordt weergegeven.
parameters:
callback: () => void
Voorbeeld:
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)
Deze listener wordt geactiveerd wanneer de toestemmingslaag gesloten is, ongeacht of de gebruiker een keuze heeft gemaakt of deze heeft afgewezen.
parameters:
callback: () => void
Voorbeeld:
import { addCloseConsentLayerListener } from 'cm-sdk-react-native-v3';
const closeSubscription = addCloseConsentLayerListener(() => {
console.log('Consent layer has been closed');
// Resume normal app flow
});
addErrorListener(callback)
Deze listener wordt geactiveerd wanneer er een fout optreedt tijdens het toestemmingsproces, zoals netwerkstoringen, time-outfouten of configuratieproblemen.
parameters:
callback: (error: string) => voiderror: Een tekenreeks die de fout beschrijft die is opgetreden
Voorbeeld:
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)
Deze listener wordt geactiveerd wanneer de gebruiker op een koppeling in de toestemmingslaag klikt (zoals koppelingen naar het privacybeleid of de servicevoorwaarden).
parameters:
callback: (url: string) => voidurl: De URL waarop is geklikt
Voorbeeld:
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. Integratie met Apple Tracking Transparency (ATT)
Als u tracking of analytics in uw app gebruikt, raden we u aan de handleiding te lezen ATT-implementatie hier.
4. Een aangepaste lay-out maken
Om een aangepaste weergave van de WKWebView te maken, bijvoorbeeld door de positie of achtergrond te wijzigen, kunt u de configuratie die is doorgegeven aan het ConsentLayerUIConfig-object als volgt wijzigen:
ConsentLayerUIConfig(
position: .halfScreenTop,
backgroundStyle: .dimmed(.grey, 0.75),
cornerRadius: 20,
respectsSafeArea: false,
allowsOrientationChanges: true)5. Loggen
Wanneer u onze iOS SDK gebruikt, kan het nodig zijn om loginformatie te debuggen of analyseren voor verschillende doeleinden. De logs die door onze SDK worden gegenereerd, zijn getagd onder "CMP", zodat u eenvoudig de relevante logs kunt filteren en bekijken. Raadpleeg voor meer informatie deze sectie van onze documentatie.
6. Platformwaarschuwingen
- Android negeert momenteel backgroundStyle-overschrijvingen en customRect/custom positie; er wordt altijd een gedimde achtergrond op volledig scherm weergegeven.
- iOS ondersteunt gedimd/kleur/vervagen/geen en customRect.
