1. Installazione

consentmanager SDK è una soluzione completa per la gestione del consenso degli utenti nelle applicazioni mobili. Progettato per gestire la conformità al GDPR, le preferenze di privacy degli utenti e la trasparenza del tracciamento pubblicitario, questo SDK offre un'integrazione perfetta per le piattaforme iOS e Android. Inoltre, offre plugin/bridge wrapper per React Native, Flutter e Unity, rendendolo versatile in vari ambienti di sviluppo.

Questo documento illustra la procedura di installazione e le funzionalità messe a disposizione dei nostri clienti che sviluppano app con React Native per accedere al nostro SDK CMP per la gestione del consenso tramite il nostro React Native Native Bridge. Per ulteriori dettagli, consulta la nostra documentazione di riferimento API. 

1.1 Fasi – Descrizione di alto livello

1. Integrazione e configurazione:

   • Integra l'SDK nella tua app.
   • Configura le impostazioni dell'SDK in base alle tue esigenze.

2. Creazione di un'istanza e visualizzazione del Consent Layer:

   • All'avvio dell'app, crea un'istanza della CMPManager classe. Questa istanza gestirà il processo di consenso.
   • L'SDK visualizzerà automaticamente la schermata di consenso se necessario.

3. Elaborazione dei dati relativi al consenso degli utenti:

   • Una volta raccolti i consensi, le informazioni vengono archiviate e sono disponibili per l'interrogazione tramite diverse proprietà e metodi esposti dal nostro SDK. Avrai informazioni sui consensi rifiutati o accettati, sui fornitori e sulle finalità.

1.2 Panoramica dell'API di configurazione

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 (tramite l'helper BackgroundStyle):
  • dimmed(color?, opacity?)
  • color(color)
  • blur(blurEffectStyle: light | dark | extraLight)
  • none
• ATTStatus: NotDetermined (0), Restricted (1), Denied (2), Authorized (3)
  

1.3 Integrazione e configurazione

NPM

Abbiamo pubblicato il nostro bridge React Native sia su NPM (architettura vecchia e nuova) che sui nostri repository pubblici (i tarball per il collegamento diretto sono disponibili sia per l'architettura vecchia che per quella nuova). Esegui questa riga sul tuo terminale:

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

Collegamenti (React Native 0.59 e versioni precedenti)

Se stai utilizzando React Native 0.59 o versioni precedenti, devi collegare i moduli nativi manualmente:

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

1.4 Creazione di un'istanza e visualizzazione del layer di consenso

Dovrai configurare le informazioni CMP tramite il setUrlConfig metodo, che gestisce la configurazione del CMP, come Code-ID e lingua predefinita, e setWebViewConfig, che configurerà l’aspetto della WebView che visualizzerà il layer di consenso. A quel punto, sarai pronto per utilizzare il metodo checkAndOpen(false) per recuperare automaticamente i dati necessari dal nostro server e determinare se la schermata di consenso debba essere mostrata o meno. Il boolean parametro determina se il layer di consenso verrà aperto nella pagina delle impostazioni (true) che permetterà agli utenti di personalizzare le proprie scelte o se il layer di consenso visualizzerà (false) la pagina di design predefinita del tuo CMP.  

Esempio:

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

L'SDK mostrerà automaticamente la schermata di consenso a questo punto (banner sui cookie), tramite un WebView creato dal nostro SDK, che visualizzerà il layer di consenso con il testo e i pulsanti in base alle configurazioni del tuo CMP (scelte tramite il Code-ID del tuo CMP), raccoglierà i dati e salverà le informazioni sul consenso nell’area NSUserDefaults/UserPreferences del dispositivo, in modo che gli altri SDK possano leggerle.

2. Trattamento dei dati relativi al consenso degli utenti

2.1 Verifica dei consensi degli utenti

Il nostro SDK offre diversi metodi per verificare e recuperare le informazioni sul consenso. Il principale è getUserStatus, come mostrato nell'esempio qui sotto. Per ulteriori informazioni, 

// 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'
    ),
  },

Per ulteriori informazioni sugli altri metodi, consulta la nostra documentazione completa delle API degli SDK nativi iOS e Android sottostanti. 

2.2 Riapertura del Consent Layer per verificare le scelte degli utenti

Per consentire all'utente di verificare o modificare le proprie scelte, puoi semplicemente chiamare forceOpen()

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

Questo metodo visualizzerà il layer di consenso tramite la stessa istanza WebView creata nei passaggi precedenti. 

2.3 Importazione/esportazione delle informazioni sul consenso verso altre fonti

In alcuni casi un'app nativa potrebbe contenere webview per visualizzare informazioni, come pubblicità o contenuti. Per trasmettere le informazioni sul consenso dall'SDK alla webview ed evitare banner sui cookie duplicati, puoi recuperare la stringa di consenso utilizzando exportCMPInfo. Questo esporterà la stringa di consenso con il consenso e tutti gli ulteriori dati necessari al CMP. Puoi quindi passare queste informazioni al CMP presente nella tua webview aggiungendole all'URL richiamato nella webview. Per ulteriori informazioni, consulta la nostra pagina dedicata a questo caso d'uso. 

Un altro caso d'uso è il consenso cross-device, in cui si importa il consenso da un'altra fonte sul dispositivo. In questo caso, puoi sostituire checkAndOpen con importCMPInfo con la stringa di consenso che hai recuperato dal sito web, ad esempio. 

2.4 Event Listeners

L'SDK fornisce diversi listener di eventi che ti consentono di reagire a diversi eventi durante il flusso di consenso. Questi listener ti permettono di tracciare le interazioni degli utenti, gestire gli errori e sincronizzare lo stato della tua app con il ciclo di vita del livello di consenso.

Tutti i listener restituiscono un oggetto di sottoscrizione che può essere utilizzato per rimuovere il listener quando non è più necessario. Per rimuovere un listener, chiama .remove() sull'oggetto di sottoscrizione restituito.

Ascoltatori di eventi disponibili

addConsentListener(callback)

Questo listener viene attivato quando l'utente invia le proprie scelte di consenso (accettando, rifiutando o personalizzando le proprie preferenze).

Parametri:

callback: (consent: string, jsonObject: Object) => void
consent: La stringa di consenso in formato IAB TCF
jsonObject: Un oggetto JSON contenente informazioni dettagliate sul consenso

Esempio:

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)
Questo listener viene attivato quando all'utente viene visualizzato il layer di consenso.

Parametri:

callback: () => void

Esempio:

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)

Questo listener viene attivato quando il layer di consenso viene chiuso, indipendentemente dal fatto che l'utente abbia effettuato una scelta o lo abbia ignorato.

Parametri:

callback: () => void

Esempio:

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

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

addErrorListener(callback)

Questo listener viene attivato quando si verifica un errore durante il processo di consenso, come ad esempio problemi di rete, errori di timeout o problemi di configurazione.

Parametri:

callback: (error: string) => void
error: Una stringa che descrive l'errore verificatosi

Esempio:

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)

Questo listener viene attivato quando l'utente clicca su un link all'interno del layer di consenso (come i link all'informativa sulla privacy o ai termini di servizio).

Parametri:

callback: (url: string) => void
url: L'URL su cui è stato cliccato

Esempio:

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. Integrazione con Apple Tracking Transparency (ATT)

Se utilizzi strumenti di tracciamento o analisi nella tua app, ti consigliamo di leggere la guida sull'implementazione dell'ATT qui.

4. Creazione di un layout personalizzato

Per creare una visualizzazione personalizzata di WKWebView, ad esempio modificandone il posizionamento o lo sfondo, puoi modificare la configurazione passata all'oggetto ConsentLayerUIConfig come di seguito:

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

5. Registrazione

Quando utilizzi il nostro SDK per iOS, potresti avere la necessità di eseguire il debug o analizzare le informazioni di log per vari scopi. I log generati dal nostro SDK sono contrassegnati con "CMP", consentendoti di filtrare facilmente e visualizzare solo i log rilevanti. Per ulteriori informazioni, consulta questa sezione della nostra documentazione.

6. Avvertenze relative alla piattaforma

• Expo non è supportato
• Attualmente Android ignora le sostituzioni di backgroundStyle e le posizioni customRect/custom; mostra sempre uno sfondo a schermo intero sfumato.
• iOS supporta dimmed/color/blur/none e customRect.