Como integrar el SDK de UniConsent CMP para React Native

Esta guia explica como integrar el SDK de UniConsent CMP en su aplicacion React Native para gestionar el consentimiento GDPR IAB TCF 2.3.

Puede encontrar una aplicacion de demostracion integrada con este SDK en el directorio UniConsentDemo proporcionado junto con el paquete del SDK.

Requisitos previos

• Un plan de UniConsent CMP que incluya soporte para aplicaciones moviles.
• El paquete del SDK de UniConsent para React Native (por ejemplo, uniconsent-react-native-sdk-26.2.0.zip), descargado desde su panel de UniConsent u obtenido del soporte tecnico.
• Un entorno de desarrollo React Native funcional.

Primeros pasos (Instalacion)

Instalar el paquete del SDK

Descargue y descomprima el paquete del SDK (por ejemplo, uniconsent-react-native-sdk-26.2.0.zip). Dentro encontrara:

• uniconsent-react-native-sdk-26.2.0.tgz — Paquete del SDK instalable via npm
• uniconsent-sdk/ — Archivos de la biblioteca del SDK precompilados
• UniConsentDemo/ — Aplicacion de demostracion
• README.md — Documentacion

Instale el archivo .tgz usando 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>

Ejemplo: Si coloca el archivo .tgz en la raiz de su proyecto:

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

Instalar dependencias de pares (Peer Dependencies)

Este SDK requiere las siguientes dependencias de pares:

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

Instalar Pods de iOS

Si esta desarrollando para iOS, navegue al directorio ios de su proyecto e instale los pods:

cd ios
pod install
cd ..

Personalizar la interfaz de consentimiento

Antes de integrar el SDK, personalice la apariencia del banner de consentimiento en el panel de UniConsent para que coincida con su marca y optimice las tasas de consentimiento.

Paso 1: Estilo de marca en el panel

Vaya a Projects → Seleccione su Proyecto → Settings → Step 5: UI & Style Settings para configurar:

• Main Button Colour — Establezca el color del boton de accion principal para que coincida con su marca
• Main Button Text Colour — Ajuste el color del texto del boton principal para mejorar la legibilidad
• Background Colour — Configure el color de fondo del banner para que se integre con su aplicacion
• Text Colour — Asegure que el texto del cuerpo tenga el contraste adecuado

Paso 2: Estilos avanzados con CSS personalizado (Opcional)

Para un control mas preciso, agregue CSS personalizado en el campo CSS Content en el Paso 5. Esto se recomienda para que el banner se sienta nativo en su aplicacion y logre la mejor tasa de consentimiento:

/* 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;
}

Consejo: Una interfaz de consentimiento bien personalizada que se sienta nativa en su aplicacion generalmente logra tasas de consentimiento mas altas. Los usuarios son mas propensos a interactuar positivamente con un banner que coincide con la apariencia que esperan.

Uso

Inicializar el SDK mediante Provider

Envuelva el componente raiz de su aplicacion (o la parte relevante) con UniConsentProvider. Debe proporcionar su licenseId (Publisher ID/pid de 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;

Modos de visualizacion

El SDK admite tres modos de visualizacion para la interfaz del CMP, configurados mediante la propiedad displayMode en UniConsentProvider:

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

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

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

Manejador de eventos

Escuche los eventos del ciclo de vida del SDK con la propiedad onEvent en UniConsentProvider.

Tipos de eventos disponibles:

• 'sdkInit' — Inicio de la inicializacion del SDK
• 'ready' — Inicializacion del SDK completada
• 'uiDisplay' — La interfaz de consentimiento se muestra
• 'uiClose' — La interfaz de consentimiento se cierra

<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>

Mostrar la interfaz del CMP

Utilice el hook useConsent dentro de un componente dentro del Provider para obtener la funcion openCMP, luego llamela cuando sea necesario (por ejemplo, al presionar un boton).

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

Verificar el consentimiento de forma programatica

Utilice las funciones de utilidad para verificar el estado del consentimiento directamente sin el 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();

Sincronizar el consentimiento con WebView

Si su aplicacion abre un WebView que carga una pagina web con la etiqueta de UniConsent CMP, puede pasar el estado de consentimiento nativo para que la etiqueta del CMP reconozca el consentimiento existente y no muestre el banner nuevamente.

Utilice getConsentSyncScript() con injectedJavaScriptBeforeContentLoaded para inyectar el consentimiento antes de que se ejecuten los scripts de la 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}
    />
  );
};

Utilidades de depuracion

El SDK proporciona funciones auxiliares para desarrollo y depuracion:

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

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

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

Configuracion

Propiedades de UniConsentProvider

Referencia de la API

Componentes y Hooks

Funciones de utilidad

Tipos exportados

Campos de ConsentData

Notas

• Acceso a la configuracion de privacidad: Su aplicacion debe proporcionar a los usuarios una forma persistente (por ejemplo, un boton o enlace de "Configuracion de privacidad", generalmente en un menu de ajustes) para acceder y actualizar sus opciones de consentimiento. Este boton debe llamar a la funcion openCMP() obtenida del hook useConsent.
• Verificacion automatica de consentimiento: El UniConsentProvider verifica automaticamente el estado del consentimiento cuando su aplicacion se inicia, incluyendo si la Global Vendor List (GVL) ha sido actualizada desde la ultima vez que el usuario otorgo su consentimiento. Si la version de la GVL ha cambiado, se solicitara nuevamente el consentimiento al usuario.