Come integrare l'SDK della CMP di UniConsent per React Native

Questa guida spiega come integrare l'SDK della CMP di UniConsent nella tua applicazione React Native per gestire il consenso GDPR IAB TCF 2.4.

Nella directory UniConsentDemo, fornita insieme al pacchetto dell'SDK, trovi un'app demo con questo SDK integrato.

Prerequisiti

• Un piano CMP di UniConsent che includa il supporto per le app mobili.
• Il pacchetto SDK di UniConsent per React Native (ad es. uniconsent-react-native-sdk-26.9.0.zip), scaricato dalla dashboard di UniConsent o ottenuto dal supporto.
• Un ambiente di sviluppo React Native funzionante.

Per iniziare (installazione)

Installa il pacchetto dell'SDK

Scarica ed estrai il pacchetto dell'SDK (ad es. uniconsent-react-native-sdk-26.9.0.zip). Al suo interno troverai:

• uniconsent-react-native-sdk-26.9.0.tgz: pacchetto SDK installabile con npm
• uniconsent-sdk/: file precompilati della libreria SDK
• UniConsentDemo/: applicazione demo
• README.md: documentazione

Installa il file .tgz con npm o Yarn:

# Replace <path-to-package-file.tgz> with the actual path to the file
npm install <path-to-package-file.tgz>
# or
yarn add <path-to-package-file.tgz>

Esempio: se inserisci il file .tgz nella radice del progetto:

npm install ./uniconsent-react-native-sdk-26.9.0.tgz
# or
yarn add file:./uniconsent-react-native-sdk-26.9.0.tgz

Installa le peer dependency

Questo SDK richiede le seguenti peer dependency:

npm install react-native-webview react-native-default-preference
# or
yarn add react-native-webview react-native-default-preference

Installa i pod iOS

Se sviluppi per iOS, vai alla directory ios del progetto e installa i pod:

cd ios
pod install
cd ..

Personalizzare l'interfaccia del consenso

Prima di integrare l'SDK, personalizza l'aspetto del banner di consenso nella dashboard di UniConsent in modo che corrisponda al tuo brand e ottimizzi i tassi di consenso.

Passaggio 1: stile del brand nella dashboard

Vai a Projects → Select your Project → Settings → Step 5: UI & Style Settings per configurare:

• Main Button Colour: imposta il colore del pulsante di azione principale in linea con il tuo brand
• Main Button Text Colour: regola il colore del testo del pulsante principale per garantirne la leggibilità
• Background Colour: imposta il colore di sfondo del banner in armonia con la tua app
• Text Colour: assicurati che il testo abbia un contrasto adeguato

Passaggio 2: stile avanzato con CSS personalizzato (facoltativo)

Per un controllo più preciso, aggiungi CSS personalizzato nel campo CSS Content dello Step 5. È consigliato per rendere il banner parte integrante della tua app e ottenere il miglior tasso di consenso:

/* Example: Style the accept button to match your brand */
.unic-btn-accept {
  background-color: #4CAF50;
  border-radius: 8px;
  font-weight: 600;
}

/* Example: Adjust banner font */
.unic-banner {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

/* Example: Make the reject button less prominent */
.unic-btn-reject {
  background-color: transparent;
  border: 1px solid #ccc;
  color: #666;
}

Suggerimento: un'interfaccia del consenso ben personalizzata, che risulti nativa nella tua app, ottiene in genere tassi di consenso più elevati. Gli utenti sono più propensi a interagire positivamente con un banner che corrisponde all'aspetto che si aspettano.

Utilizzo

Inizializza l'SDK tramite il Provider

Racchiudi il componente radice della tua applicazione (o la parte pertinente) con UniConsentProvider. Devi fornire il tuo licenseId (Publisher ID/pid di UniConsent).

// Your main App file (e.g., App.tsx or index.js)
import React from 'react';
import { UniConsentProvider } from 'uniconsent-sdk';
import YourAppRootComponent from './src/YourAppRootComponent';

const App = () => {
  return (
    <UniConsentProvider licenseId="YOUR_LICENSE_ID">
      <YourAppRootComponent />
    </UniConsentProvider>
  );
};

export default App;

Modalità di visualizzazione

L'SDK supporta tre modalità di visualizzazione per l'interfaccia della CMP, configurabili tramite la prop displayMode di UniConsentProvider:

Modalità	Descrizione
'fullScreen'	Pagina a schermo intero (predefinita)
'bottomSheet'	Pannello modale ancorato alla parte inferiore dello schermo
'dialog'	Finestra di dialogo modale centrata

// Full screen (default — no prop needed)
<UniConsentProvider licenseId="YOUR_LICENSE_ID">

// Bottom sheet
<UniConsentProvider licenseId="YOUR_LICENSE_ID" displayMode="bottomSheet">

// Bottom sheet at 70% of the screen height
<UniConsentProvider licenseId="YOUR_LICENSE_ID" displayMode="bottomSheet" heightRatio={0.7}>

// Center dialog
<UniConsentProvider licenseId="YOUR_LICENSE_ID" displayMode="dialog">

// Center dialog at 80% width and 60% height
<UniConsentProvider licenseId="YOUR_LICENSE_ID" displayMode="dialog" widthRatio={0.8} heightRatio={0.6}>

Dimensione personalizzata (facoltativa)

Disponibile a partire dalla versione 26.8.0 dell'SDK.

Entrambi i rapporti sono facoltativi: ogni modalità di visualizzazione funziona anche senza. Passa un rapporto (una frazione dello schermo, maggiore di 0 e al massimo 1) solo per sovrascrivere la dimensione predefinita; i valori non validi generano un RangeError:

Prop	Si applica a	Valore predefinito se omesso
heightRatio	'bottomSheet', 'dialog'	Sheet: 90% dello schermo. Dialog: 70%
widthRatio	solo 'dialog'	90% della larghezza dello schermo, fino a 500

I rapporti che non si applicano alla modalità di visualizzazione scelta vengono ignorati ('fullScreen' li ignora entrambi).

Gestore degli eventi

Ascolta gli eventi del ciclo di vita dell'SDK con la prop onEvent di UniConsentProvider.

Tipi di evento disponibili:

• 'sdkInit': inizializzazione dell'SDK avviata
• 'ready': inizializzazione dell'SDK completata
• 'uiDisplay': l'interfaccia del consenso viene mostrata
• 'uiClose': l'interfaccia del consenso viene chiusa

<UniConsentProvider
  licenseId="YOUR_LICENSE_ID"
  onEvent={(event) => {
    switch (event.type) {
      case 'ready':
        console.log('SDK ready');
        break;
      case 'uiClose':
        console.log('Consent UI closed');
        break;
    }
  }}
>
  <YourAppRootComponent />
</UniConsentProvider>

Mostrare l'interfaccia della CMP

Usa l'hook useConsent in un componente all'interno del Provider per ottenere la funzione openCMP, quindi chiamala quando necessario (ad es. alla pressione di un pulsante).

import React from 'react';
import { View, Text, Button, ActivityIndicator } from 'react-native';
import { useConsent } from 'uniconsent-sdk';

const ConsentInfoComponent = () => {
  const { consentStatus, isLoading, openCMP } = useConsent();

  return (
    <View>
      <Text>Consent Status:</Text>
      {isLoading ? (
        <ActivityIndicator />
      ) : (
        <Text>{consentStatus ?? 'Initializing...'}</Text>
      )}
      <Button
        title="Manage Privacy Settings"
        onPress={openCMP}
        disabled={isLoading}
      />
    </View>
  );
};

Verificare il consenso programmaticamente

Usa le funzioni di utilità per verificare lo stato del consenso direttamente, senza l'hook:

import {
  getTCString,
  isEURegion,
  isPurposeConsented,
  isVendorConsented,
  getConsentData,
} from 'uniconsent-sdk';

// Get the full TC String
const tcString = await getTCString();

// Check if user is in EU/EEA region
const inEU = await isEURegion();

// Check if a specific TCF purpose has consent (1-based ID)
const hasPurpose1 = await isPurposeConsented(1);

// Check if a specific vendor has consent (1-based ID)
const hasVendor755 = await isVendorConsented(755);

// Get all consent data as a single object
const consentData = await getConsentData();

Primo livello personalizzato (Accetta tutto / Rifiuta tutto)

Disponibile a partire dalla versione 26.7.0 dell'SDK. Se crei una tua interfaccia del consenso di primo livello invece di mostrare la webview della CMP, puoi salvare il consenso direttamente:

import { agreeAll, rejectAll } from 'uniconsent-sdk';

// Grant consent for all purposes, special features and vendors
const saved = await agreeAll();

// Reject all purposes, special features and vendors
const rejected = await rejectAll();

Entrambe le API salvano gli stessi valori di consenso del flusso dell'interfaccia della CMP (chiavi IAB TCF, consenso aggiuntivo e segnali di Consent Mode), aggiornano il consentStatus del provider e inviano l'evento uiClose a onEvent. Usano il licenseId registrato da UniConsentProvider, quindi chiamale dopo che il provider è stato montato.

Importante: il tuo primo livello personalizzato deve comunque soddisfare i requisiti IAB TCF (indicare finalità e fornitori, e offrire accettazione e rifiuto con uguale evidenza). Gli utenti devono comunque poter aprire l'interfaccia completa della CMP (openCMP()) per effettuare scelte granulari.

Sincronizzare il consenso con la WebView

Se la tua app apre una WebView che carica una pagina web con il tag della CMP di UniConsent, puoi passare lo stato del consenso nativo in modo che il tag della CMP riconosca il consenso esistente e non mostri di nuovo il banner.

Usa getConsentSyncScript() con injectedJavaScriptBeforeContentLoaded per iniettare il consenso prima che venga eseguito qualsiasi script della pagina:

import React, { useState, useEffect } from 'react';
import { WebView } from 'react-native-webview';
import { getConsentSyncScript } from 'uniconsent-sdk';

const MyWebView = () => {
  const [consentScript, setConsentScript] = useState<string | null>(null);

  useEffect(() => {
    getConsentSyncScript().then(setConsentScript);
  }, []);

  if (!consentScript) return null;

  return (
    <WebView
      source={{ uri: 'https://example.com' }}
      injectedJavaScriptBeforeContentLoaded={consentScript}
    />
  );
};

Utilità di debug

L'SDK fornisce funzioni di supporto per lo sviluppo e il debug:

import { listKV, clearKV } from 'uniconsent-sdk';

// Log all stored consent keys to console
await listKV();

// Clear all stored consent data
await clearKV();

Configurazione

Prop di UniConsentProvider

Prop	Tipo	Obbligatoria	Predefinito	Descrizione
licenseId	string	Sì	—	Il tuo Publisher ID (pid) di UniConsent.
displayMode	CMPDisplayMode	No	'fullScreen'	Stile di visualizzazione della CMP: 'fullScreen', 'bottomSheet' o 'dialog'.
heightRatio	number	No	Sheet: 0.9, dialog: 0.7	Altezza dell'interfaccia come frazione dell'altezza dello schermo in (0, 1]. Si applica a 'bottomSheet' e 'dialog'.
widthRatio	number	No	0.9 (massimo 500)	Larghezza della finestra di dialogo come frazione della larghezza dello schermo in (0, 1]. Si applica solo a 'dialog'.
onEvent	CMPEventCallback	No	—	Callback per gli eventi del ciclo di vita dell'SDK (sdkInit, ready, uiDisplay, uiClose).

Riferimento API

Componenti e hook

Export	Descrizione
UniConsentProvider	Componente React con cui racchiudere l'applicazione. Richiede la prop licenseId.
useConsent()	Hook che restituisce { consentStatus, isLoading, openCMP }.

Funzioni di utilità

Funzione	Restituisce	Descrizione
getTCString()	Promise<string>	Ottiene la stringa di consenso IAB TCF.
isEURegion()	Promise<boolean>	Verifica se l'utente si trova in una regione UE/SEE.
isPurposeConsented(purposeId)	Promise<boolean>	Verifica il consenso per una specifica finalità TCF (ID a partire da 1).
isVendorConsented(vendorId)	Promise<boolean>	Verifica il consenso per uno specifico fornitore TCF (ID a partire da 1).
getConsentData()	Promise<ConsentData>	Ottiene un oggetto completo con i dati del consenso.
getConsentSyncScript()	Promise<string>	Ottiene uno snippet JS per iniettare il consenso in una WebView.
agreeAll()	Promise<boolean>	Concede il consenso per tutte le finalità, le funzionalità speciali e i fornitori (primo livello personalizzato).
rejectAll()	Promise<boolean>	Rifiuta tutte le finalità, le funzionalità speciali e i fornitori (primo livello personalizzato).
listKV()	Promise<void>	Debug: registra nella console tutte le chiavi di consenso memorizzate.
clearKV()	Promise<void>	Debug: cancella tutti i dati di consenso memorizzati.

Tipi esportati

Tipo	Descrizione
CMPDisplayMode	'fullScreen' | 'bottomSheet' | 'dialog'
CMPEventType	'sdkInit' | 'ready' | 'uiDisplay' | 'uiClose'
CMPEventCallback	(event: { type: CMPEventType }) => void
ConsentContextValue	Struttura del valore restituito da useConsent().
ConsentData	Struttura del valore restituito da getConsentData().

Campi di ConsentData

Campo	Tipo	Descrizione
tcString	string	Stringa di consenso IAB TCF completa.
isEURegion	boolean	Indica se l'utente si trova in una regione UE/SEE.
gdprApplies	boolean	Flag che indica se si applica il GDPR.
cmpSdkId	number	ID registrato dell'SDK della CMP (68 per UniConsent).
cmpSdkVersion	number	Versione dell'SDK della CMP.
policyVersion	number	Versione della policy TCF.
purposeConsents	string	Stringa binaria delle finalità con consenso (ad es. "10110").
vendorConsents	string	Stringa binaria dei fornitori con consenso.
additionalConsent	string	Stringa Google Additional Consent (AC).
gvlVersion	number	Versione della Global Vendor List utilizzata.

Note

• Accesso alle impostazioni della privacy: la tua applicazione deve offrire agli utenti un modo sempre disponibile (ad es. un pulsante o un link "Impostazioni privacy", spesso in un menu delle impostazioni) per accedere alle proprie scelte di consenso e aggiornarle. Questo pulsante deve chiamare la funzione openCMP() ottenuta dall'hook useConsent.
• Verifica automatica del consenso: UniConsentProvider verifica automaticamente lo stato del consenso all'avvio dell'app, controllando anche se la Global Vendor List (GVL) è stata aggiornata dall'ultima volta in cui l'utente ha dato il consenso. Se la versione della GVL è cambiata, all'utente verrà richiesto nuovamente il consenso.

Registro delle modifiche

26.9.0

• Supporto per IAB TCF 2.4