Guía del repositorio del SDK de React Native

Acerca del SDK de React Native de Braze

El SDK de React Native de Braze conecta tus aplicaciones de iOS y Android con Braze: perfiles de usuario, superficies de mensajería, análisis y conmutadores de características. Encapsula el SDK de Swift de Braze y el SDK de Android de Braze nativos tras una API de JavaScript.

La inicialización se controla desde JavaScript: configuras los ajustes nativos (push, registro, delegados) en los recursos de Android y en el AppDelegate de iOS, y después llamas a Braze.initialize(apiKey, endpoint) desde JavaScript para iniciar el SDK. Así tienes control total sobre cuándo se inicializa el SDK y con qué credenciales. Después de la inicialización, llama a otros métodos del SDK (por ejemplo, changeUser o logCustomEvent) según los necesites.

Lo que puedes hacer

• Gestión de usuarios: Identifica usuarios y establece campos de perfil, atributos personalizados, alias y grupos de suscripción
• Mensajes dentro de la aplicación: Interfaz de usuario predeterminada de Braze o gestión personalizada mediante suscripciones y API de registro
• Content Cards: Interfaz de usuario de la fuente predeterminada, u obtén las tarjetas y crea tu propia interfaz de usuario
• Banners: Banners HTML basados en ubicaciones, incluido BrazeBannerView
• Notificaciones push: Solicitudes de permiso, registro de tokens y agentes de escucha de cargas útiles (consulta las notas de cada plataforma en Configuración nativa)
• Conmutadores de características: Actualiza, lee propiedades y registra impresiones
• Análisis: Eventos personalizados, compras y vaciado inmediato
• Controles del SDK: Habilita o deshabilita el SDK, borra los datos locales y usa firmas de autenticación del SDK

Requisitos previos

• Cuenta de Braze con clave de API de la aplicación y punto final de SDK
• Entorno de desarrollo de React Native (configuración del entorno de React Native)
• iOS: Xcode, CocoaPods (cd ios && pod install)
• Android: Android Studio / Gradle; complemento de Kotlin para Gradle según lo requiera tu plantilla de React Native
• Push (si lo utilizas): configuración de FCM (Android) y APNs (iOS) según la documentación de push

Para saber dónde encontrar las credenciales en el panel, sigue el resumen de la integración.

Instalación

1
2
3

npm install @braze/react-native-sdk
# or:
# yarn add @braze/react-native-sdk

Inicio rápido

Esta sección muestra la configuración mínima necesaria para inicializar el SDK de React Native de Braze.

1. Instala el paquete npm.
2. Completa la configuración nativa para Android e iOS (configuración, permisos y notificaciones push si las necesitas).
3. Inicializa el SDK desde JavaScript y empieza a utilizarlo:

1
2
3
4
5
6
7
8
9

import Braze from "@braze/react-native-sdk";

// Initialize the SDK — call early in your app lifecycle (e.g. in a useEffect).
// The API key and endpoint are passed from JavaScript; native configuration
// (push, logging, etc.) is applied automatically from your native setup.
Braze.initialize("<YOUR_API_KEY>", "<YOUR_SDK_ENDPOINT>");

Braze.changeUser("user-123");
Braze.logCustomEvent("button_clicked", { screen: "home" });

Las definiciones de tipos de TypeScript se incluyen con el paquete (src/index.d.ts en GitHub).

Si vuelves a llamar a Braze.initialize con credenciales diferentes, se elimina la instancia actual y se vuelve a crear, lo que permite reinicializar el SDK a mitad de sesión.

Configuración nativa

Fuente de referencia: Las pantallas paso a paso, los cambios en Gradle y CocoaPods, y la lista completa de claves XML de Android están en la guía para desarrolladores de React Native de Braze. Los siguientes fragmentos de código son ejemplos mínimos.

Android

• Añade el complemento de Gradle para Kotlin en tu build.gradle raíz si tu plantilla aún no lo incluye (las versiones dependen de tu versión de React Native).
• Añade un archivo de recursos braze.xml en res/values con tu configuración. Habilita la inicialización diferida para que el SDK espere a que se llame a Braze.initialize() desde JavaScript antes de iniciarse. Los demás valores de configuración (push, tiempo de espera de la sesión, etc.) se siguen leyendo desde este archivo y se aplican en el momento de la inicialización.
• Asegúrate de incluir permisos básicos como INTERNET y ACCESS_NETWORK_STATE en AndroidManifest.xml.
• Para las notificaciones push, completa la integración de FCM y configura el ID de remitente y los indicadores de registro específicos de Braze que se describen en la documentación.

1
2
3
4
5
6
7
8
9
10

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <!-- Enable delayed initialization so the SDK starts when
       Braze.initialize() is called from JavaScript. -->
  <bool name="com_braze_enable_delayed_initialization">true</bool>

  <!-- Additional native configuration (applied at initialization time) -->
  <bool name="com_braze_firebase_cloud_messaging_registration_enabled">true</bool>
  <string translatable="false" name="com_braze_firebase_cloud_messaging_sender_id">YOUR_SENDER_ID</string>
</resources>

Nota

** La clave de API y el endpoint ya no se establecen en braze.xml: se pasan desde JavaScript mediante Braze.initialize(apiKey, endpoint).

iOS

1

cd ios && pod install

Usa BrazeReactInitializer.configure en tu AppDelegate para registrar la configuración nativa. Los closures que proporciones se almacenan y se aplican más tarde, cuando se llama a Braze.initialize(apiKey, endpoint) desde JavaScript.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import BrazeKit
import braze_react_native_sdk

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  static var braze: Braze? = nil

  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    // Register native configuration for when JS calls Braze.initialize().
    BrazeReactInitializer.configure { config in
      config.logger.level = .info
      config.push.automation = true
    } postInitialization: { braze in
      AppDelegate.braze = braze
    }

    // ... React Native setup
    return true
  }
}

• Closure configure: recibe un Braze.Configuration y te permite establecer propiedades de configuración nativas (registro, push, sesiones, etc.). La clave de API y el endpoint se proporcionan desde JavaScript, así que no los estableces aquí.
• Closure postInitialization (opcional): recibe la instancia activa de Braze después de su creación, para tareas de configuración que requieren la instancia (p. ej., almacenar una referencia o establecer delegados).

Nota

** BrazeReactInitializer.configure es una API pensada principalmente para Swift que reemplaza al obsoleto BrazeReactBridge.initBraze(_:). También resuelve un problema de resolución de tipos de Swift con Braze.Configuration en el puente de Objective-C.

Referencia de configuración

En React Native, la configuración es nativa: Android lee res/values/braze.xml e iOS utiliza cierres registrados mediante BrazeReactInitializer.configure. Ambas se aplican cuando se llama a Braze.initialize(apiKey, endpoint) desde JavaScript.

Android (braze.xml)

Los valores predeterminados se encuentran en XML; BrazeConfig.Builder puede sobrescribirlos al iniciar. La lista oficial de claves y tipos se encuentra en la guía de integración del SDK de Android y en BrazeConfigurationProvider (cada propiedad de Kotlin corresponde a recursos com_braze_* documentados).

Entradas de uso habitual:

iOS (Braze.Configuration)

Establece las propiedades de configuración nativas en el cierre configure que se pasa a BrazeReactInitializer.configure. El cierre recibe una instancia de Braze.Configuration: la clave de API y el endpoint se establecen automáticamente a partir de la llamada Braze.initialize de JavaScript. Detalles completos: Braze.Configuration y los tipos anidados api, push, logger y location.

El puente de React Native establece api.sdkFlavor y los metadatos del SDK específicos de React al inicializarse; no los sobrescribas a menos que la documentación de Braze te lo indique.

API de JavaScript / TypeScript

La exportación predeterminada del paquete es la clase Braze con métodos estáticos (por ejemplo, Braze.changeUser y Braze.logPurchase). Las constantes como Braze.Events, Braze.Genders y Braze.NotificationSubscriptionTypes están adjuntas a la misma exportación.

Características principales

Administración de usuarios

1
2
3
4
5
6
7

import Braze from "@braze/react-native-sdk";

Braze.changeUser("user-123");
Braze.setEmail("[email protected]");
Braze.setCustomUserAttribute("plan", "premium");
Braze.addAlias("external_id", "marketing_id");
Braze.addToSubscriptionGroup("NEWSLETTER_GROUP_UUID");

Autenticación del SDK opcional: pasa una firma como segundo argumento a changeUser, o llama a Braze.setSdkAuthenticationSignature(signature) cuando esté habilitada en el panel.

Mensajes dentro de la aplicación

• Con la interfaz de usuario predeterminada de Braze, sigue la documentación de mensajes dentro de la aplicación. Por lo general, no necesitas llamar a subscribeToInAppMessage solo para mostrar la interfaz de usuario predeterminada.
• Para una gestión personalizada, suscríbete con useBrazeUI: false y luego registra las impresiones y los clics según sea necesario:

1
2
3
4
5

Braze.subscribeToInAppMessage(false, (event) => {
  const msg = event.inAppMessage;
  // Render your own UI from msg.message, msg.buttons, etc.
  Braze.logInAppMessageImpression(msg);
});

Content Cards

1
2
3
4
5
6

const cards = await Braze.getCachedContentCards();
Braze.requestContentCardsRefresh();
Braze.launchContentCards(); // default Braze UI

Braze.logContentCardImpression(cardId);
Braze.logContentCardClicked(cardId);

Escucha las actualizaciones con Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, ...).

Banners

1
2
3
4
5
6
7

import Braze from "@braze/react-native-sdk";

Braze.requestBannersRefresh(["homepage_banner"]);
const banner = await Braze.getBanner("homepage_banner");

// Or use the native Banner view:
// <Braze.BrazeBannerView placementId="homepage_banner" />

Notificaciones push

1
2
3
4
5
6
7

Braze.requestPushPermission({
  alert: true,
  badge: true,
  sound: true,
});
// Token registration is usually handled natively; see docs for your setup.
Braze.registerPushToken(token);

• getInitialPushPayload: úsalo cuando la aplicación se abra desde una notificación para evitar condiciones de carrera con Linking de RN. Requiere hooks nativos (BrazeReactUtils en iOS, BrazeReactUtils.populateInitialPushPayloadFromIntent en Android), tal como se describe en los comentarios de documentación de TypeScript y en la aplicación de ejemplo.
• Braze.addListener(Braze.Events.PUSH_NOTIFICATION_EVENT, ...) es exclusivo de Android según las definiciones de tipos públicas.

Conmutadores de características

1
2
3
4
5
6

const flag = await Braze.getFeatureFlag("new_checkout");
if (flag?.enabled) {
  const rollout = flag.getNumberProperty("rollout_percentage") ?? 0;
}
Braze.refreshFeatureFlags();
Braze.logFeatureFlagImpression("new_checkout");

Análisis y compras

1
2
3

Braze.logCustomEvent("purchase_completed", { sku: "sku-1" });
Braze.logPurchase("sku-1", "29.99", "USD", 1, { source: "cart" });
Braze.requestImmediateDataFlush();

Nota: logPurchase recibe el precio como cadena (consulta las definiciones de tipos).

Administración de datos y estado del SDK

changeUser solo le indica a Braze a qué ID de usuario debe atribuir la actividad nueva. No borra los datos del SDK almacenados en caché en el dispositivo. No existe una API de “cierre de sesión” independiente: si necesitas un cierre de sesión tradicional (borrar el estado local de Braze para que el perfil, los mensajes y los tokens en caché del usuario anterior desaparezcan de esta instalación), normalmente usarás wipeData(). Se trata de un restablecimiento local completo.

1
2
3

Braze.wipeData();
Braze.disableSDK();
Braze.enableSDK();

wipeData(): borra los datos locales de Braze para esta instalación (estado en caché de usuario, sesión y tarjetas, asociación del token de notificaciones push, etc.). Úsalo para un comportamiento similar a un cierre de sesión cuando no debas dejar el estado de Braze del usuario anterior en el dispositivo, así como para “eliminar mis datos de este dispositivo”, restablecimientos de control de calidad sin reinstalar o flujos estrictos de privacidad. changeUser por sí solo no realiza esa limpieza: solo establece qué ID de usuario recibe los eventos nuevos. En iOS, el comportamiento puede diferir del de Android (por ejemplo, la interacción con el estado de SDK deshabilitado); consulta la documentación nativa de Braze si lo usas en producción.

disableSDK(): detiene el funcionamiento del SDK (sin recopilación ni reenvío según la configuración). Úsalo para opciones de exclusión voluntaria del usuario, modos restringidos (cumplimiento normativo, configuración para menores) o depuración sin eliminar la dependencia.

enableSDK(): vuelve a activar el SDK después de disableSDK(). En iOS, es posible que la reactivación no se aplique hasta el próximo inicio de la aplicación; compruébalo en la documentación de Braze para Swift/iOS antes de depender de una reactivación inmediata.

Eventos

Suscríbete con Braze.addListener(event, callback). La llamada devuelve un objeto de suscripción; llama a .remove() sobre él para dejar de escuchar.

Configurar un agente de escucha:

1
2
3
4
5
6
7
8

import Braze from "@braze/react-native-sdk";

const subscription = Braze.addListener(
  Braze.Events.CONTENT_CARDS_UPDATED,
  (update) => {
    console.log("Content cards:", update.cards);
  }
);

Eliminar el agente de escucha:

1

subscription.remove();

En un componente de React, guarda la suscripción y llama a .remove() en tu limpieza (por ejemplo, en el retorno de un useEffect):

1
2
3
4
5
6

useEffect(() => {
  const sub = Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, (update) => {
    setCards(update.cards);
  });
  return () => sub.remove();
}, []);

Notas de integración

• Expo: utiliza el complemento Braze Expo para evitar en lo posible la configuración nativa manual.
• Nueva arquitectura / Turbo Modules: compatible con las versiones recientes del complemento; si migras, sigue la guía para desarrolladores y la configuración de ejemplo de AppDelegate y Gradle.
• Privacidad (iOS): métodos como updateTrackingPropertyAllowList admiten la configuración relacionada con el manifiesto de privacidad; consulta Manifiesto de privacidad de Swift.

- Jest: simula los módulos nativos de react-native o el módulo Turbo de Braze. Las pruebas unitarias no se publican en este repositorio.

Compatibilidad de versiones

Nota

Este SDK se ha probado con la versión 0.87.1 de React Native.

La siguiente tabla muestra las versiones de React Native compatibles con cada versión del complemento de Braze.

Respeta también los requisitos de los SDK nativos:

• Información de versiones del SDK de Android
• Información de versiones del SDK de Swift

Complemento Braze Expo

Para flujos de trabajo administrados por Expo, consulta el repositorio del complemento Braze Expo.

Aplicación de muestra

BrazeProject en este repositorio es una muestra completa (administración de usuarios, Content Cards, conmutadores de características, banners, etc.).

1
2
3

cd BrazeProject/
yarn install
npx react-native start

iOS (desde BrazeProject):

1
2

cd ios && pod install && cd ..
npx react-native run-ios

Usa RCT_NEW_ARCH_ENABLED=0 pod install si necesitas la arquitectura heredada.

Android (desde BrazeProject):

1

npx react-native run-android

Depuración y solución de problemas

Habilita el registro de Braze en la configuración nativa durante el desarrollo para que el SDK escriba en la consola del sistema (Xcode / Logcat de Android). Esto te ayuda a verificar la inicialización, los cambios de usuario y la entrega de eventos.

• iOS: en el cierre configure que pasas a BrazeReactInitializer.configure, establece config.logger.level = .debug (o .info). Reduce o desactiva el registro en producción para que los usuarios no puedan ver los registros.
• Android: usa el recurso com_braze_logger_initial_log_level en braze.xml o establece el equivalente en BrazeConfig.Builder (consulta BrazeConfigurationProvider). Usa un nivel no detallado o elimina la anulación antes del lanzamiento.

Para una solución de problemas más a fondo (comportamiento de la red, de la sesión o de la campaña), consulta la guía para desarrolladores de React Native de Braze y la documentación del SDK nativo (Swift · Android).

Recursos adicionales

• Guía para desarrolladores de Braze: React Native
• Notificaciones push: React Native
• Repositorio de GitHub
• Paquete npm

Contacto

Si tienes preguntas, ponte en contacto con el soporte técnico de Braze para obtener ayuda.

Para ver los detalles del repositorio y proyectos de ejemplo, consulta https://github.com/braze-inc/braze-react-native-sdk.