Guide du dépôt du SDK React Native

À propos du SDK React Native de Braze

Le SDK React Native de Braze connecte vos applications iOS et Android à Braze : profils utilisateurs, canaux de communication, analyses et feature flags. Il encapsule les SDK natifs Braze Swift SDK et Braze Android SDK derrière une API JavaScript.

L’initialisation est pilotée par JavaScript : vous définissez la configuration native (notifications push, journalisation, délégués) dans les ressources Android et dans l’AppDelegate iOS, puis vous appelez Braze.initialize(apiKey, endpoint) depuis JavaScript pour démarrer le SDK. Vous contrôlez ainsi entièrement le moment où le SDK s’initialise et les identifiants qu’il utilise. Une fois l’initialisation effectuée, appelez les autres méthodes du SDK (par exemple changeUser ou logCustomEvent) selon vos besoins.

Ce que vous pouvez faire

• Gestion des utilisateurs : identifiez les utilisateurs, définissez les champs de profil, les attributs personnalisés, les alias et les groupes d’abonnement
• Messages in-app : utilisez l’interface utilisateur par défaut de Braze ou une gestion personnalisée grâce aux abonnements et aux API de journalisation
• Content Cards : utilisez l’interface utilisateur du flux par défaut, ou récupérez les cartes et créez votre propre interface
• Bannières : bannières HTML basées sur des emplacements, y compris BrazeBannerView
• Notifications push : demandes d’autorisation, enregistrement des jetons, écouteurs de payload (voir les remarques sur les plateformes ci-dessous)
• Feature flags : actualisez-les, lisez leurs propriétés et enregistrez les impressions
• Analyses : événements personnalisés, achats, envoi immédiat des données
• Contrôles du SDK : activez ou désactivez le SDK, effacez les données locales et gérez les signatures d’authentification du SDK

Conditions préalables

• Compte Braze avec une clé API d’application et un endpoint SDK
• Environnement de développement React Native (configuration de l’environnement React Native)
• iOS : Xcode, CocoaPods (cd ios && pod install)
• Android : Android Studio / Gradle ; plugin Kotlin Gradle selon les exigences de votre modèle React Native
• Notifications push (le cas échéant) : configuration de FCM (Android) et des APN (iOS) conformément à la documentation sur les notifications push

Pour savoir où trouver vos identifiants dans le tableau de bord, consultez l’aperçu de l’intégration.

Installation

1
2
3

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

Démarrage rapide

Cette section présente la configuration minimale requise pour initialiser le SDK React Native de Braze.

1. Installez le package npm (voir ci-dessus).
2. Effectuez la configuration native pour Android et iOS (configuration, autorisations, notifications push si nécessaire).
3. Initialisez le SDK depuis JavaScript et commencez à l’utiliser :

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

Les définitions de types TypeScript sont fournies avec le package (src/index.d.ts sur GitHub).

Si vous appelez à nouveau Braze.initialize avec des identifiants différents, l’instance actuelle est supprimée puis recréée, ce qui permet de réinitialiser le SDK en cours de session.

Configuration native

Source de référence : Les écrans détaillés étape par étape, les modifications Gradle/CocoaPods et la liste complète des clés XML Android se trouvent dans le guide du développeur React Native de Braze. Les extraits de code ci-dessous sont des exemples minimaux.

Android

• Ajoutez le plugin Gradle Kotlin dans votre fichier build.gradle racine si votre modèle ne l’inclut pas déjà (les versions dépendent de votre version de React Native).
• Ajoutez un fichier de ressources braze.xml dans res/values avec votre configuration. Activez l’initialisation différée pour que le SDK attende l’appel à Braze.initialize() depuis JavaScript avant de démarrer. Les autres valeurs de configuration (notifications push, délai d’expiration de session, etc.) sont toujours lues depuis ce fichier et appliquées au moment de l’initialisation.
• Vérifiez que les autorisations de base, telles que INTERNET et ACCESS_NETWORK_STATE, figurent dans AndroidManifest.xml.
• Pour les notifications push, effectuez l’intégration FCM et configurez l’ID d’expéditeur ainsi que les indicateurs d’enregistrement propres à Braze décrits dans la documentation.

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>

Remarque

** La clé API et l’endpoint ne sont plus définis dans braze.xml : ils sont transmis depuis JavaScript via Braze.initialize(apiKey, endpoint).

iOS

1

cd ios && pod install

Utilisez BrazeReactInitializer.configure dans votre AppDelegate pour enregistrer la configuration native. Les closures que vous fournissez sont stockées, puis appliquées lorsque Braze.initialize(apiKey, endpoint) est appelé depuis 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 : reçoit un objet Braze.Configuration et vous permet de définir les propriétés de configuration native (journalisation, notifications push, sessions, etc.). La clé API et l’endpoint sont fournis depuis JavaScript : vous n’avez pas à les définir ici.
• Closure postInitialization (facultative) : reçoit l’instance Braze active après sa création, pour les configurations qui nécessitent l’instance (par exemple, stocker une référence ou définir des délégués).

Remarque

** BrazeReactInitializer.configure est une API conçue en priorité pour Swift qui remplace la méthode obsolète BrazeReactBridge.initBraze(_:). Elle résout également un problème de résolution de type Swift avec Braze.Configuration dans le pont Objective-C.

Référence de configuration

Dans React Native, la configuration est native : Android lit res/values/braze.xml, et iOS utilise des closures enregistrées via BrazeReactInitializer.configure. Les deux s’appliquent lorsque Braze.initialize(apiKey, endpoint) est appelé depuis JavaScript.

Android (braze.xml)

Les valeurs par défaut sont définies dans le XML ; BrazeConfig.Builder peut les remplacer au démarrage. La liste de référence des clés et de leurs types se trouve dans le guide d’intégration du SDK Android et dans BrazeConfigurationProvider (chaque propriété Kotlin correspond à une ressource com_braze_* documentée).

Entrées couramment utilisées :

iOS (Braze.Configuration)

Définissez les propriétés de configuration natives dans la closure configure transmise à BrazeReactInitializer.configure. La closure reçoit une instance de Braze.Configuration ; la clé API et l’endpoint sont définis automatiquement à partir de l’appel JavaScript Braze.initialize. Pour tous les détails, consultez Braze.Configuration et les types imbriqués api, push, logger et location.

Le pont React Native définit à l’initialisation api.sdkFlavor et les métadonnées SDK propres à React ; ne les remplacez pas, sauf si la documentation Braze vous y invite.

API JavaScript / TypeScript

L’export par défaut du paquet est la classe Braze, qui expose des méthodes statiques (par exemple Braze.changeUser, Braze.logPurchase). Les constantes comme Braze.Events, Braze.Genders et Braze.NotificationSubscriptionTypes sont rattachées à ce même export.

Fonctionnalités principales

Gestion des utilisateurs

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

Authentification SDK facultative : transmettez une signature comme second argument de changeUser, ou appelez Braze.setSdkAuthenticationSignature(signature) lorsque cette fonctionnalité est activée dans le tableau de bord.

Messages in-app

• Avec l’interface utilisateur par défaut de Braze, suivez la documentation sur les messages in-app ; en général, vous n’avez pas besoin d’appeler subscribeToInAppMessage uniquement pour afficher l’interface par défaut.
• Pour une gestion personnalisée, abonnez-vous avec useBrazeUI: false, puis enregistrez les impressions et les clics selon vos besoins :

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

Écoutez les mises à jour avec Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, ...).

Bannières

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

Notifications 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 : à utiliser lorsque l’application s’ouvre depuis une notification, afin d’éviter les conditions de concurrence avec Linking de React Native. Cette méthode nécessite une configuration native sur chaque plateforme.
  • iOS, avec les options de lancement de l’app delegate : appelez populateInitialPayloadFromLaunchOptions: sur BrazeReactUtils depuis application:didFinishLaunchingWithOptions:.
  • iOS, avec le cycle de vie des scènes : appelez populateInitialPayloadFromNotificationResponse: sur BrazeReactUtils depuis scene:willConnectToSession:options:.
  • Android : appelez BrazeReactUtils.populateInitialPushPayloadFromIntent depuis MainActivity.onCreate().
• Braze.addListener(Braze.Events.PUSH_NOTIFICATION_EVENT, ...) est réservé à Android d’après les typages publics.

Feature flags

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

Analyses et achats

1
2
3

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

Remarque : logPurchase attend le prix sous forme de chaîne de caractères (voir les typages).

Gestion des données et état du SDK

changeUser indique uniquement à Braze à quel ID utilisateur attribuer les nouvelles activités. Cette méthode n’efface pas les données du SDK mises en cache sur l’appareil. Il n’existe pas d’API de « déconnexion » distincte : si vous avez besoin d’une déconnexion classique (effacer l’état local de Braze afin que le profil, les messages et les jetons en cache de l’utilisateur précédent disparaissent de cette installation), utilisez généralement wipeData(). Il s’agit d’une réinitialisation locale complète.

1
2
3

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

wipeData() : efface les données locales de Braze pour cette installation (état mis en cache de l’utilisateur, de la session et des cartes, association du jeton push, etc.). À utiliser pour un comportement de type déconnexion lorsque vous ne devez pas laisser l’état Braze de l’utilisateur précédent sur l’appareil, ainsi que pour une fonction « supprimer mes données sur cet appareil », des réinitialisations de QA sans réinstallation ou des parcours stricts de confidentialité. changeUser seul n’effectue pas ce nettoyage : il définit uniquement l’ID utilisateur qui reçoit les nouveaux événements. Sur iOS, le comportement peut différer de celui d’Android (par exemple, l’interaction avec l’état désactivé du SDK) ; consultez la documentation native de Braze si vous déployez cette fonctionnalité en production.

disableSDK() : arrête le fonctionnement du SDK (aucune collecte ni transmission selon la configuration). À utiliser pour les options de désabonnement de l’utilisateur, les modes restreints (conformité, paramètres pour enfants) ou le débogage sans supprimer la dépendance.

enableSDK() : réactive le SDK après disableSDK(). Sur iOS, la réactivation peut ne pas prendre effet avant le prochain lancement de l’application ; vérifiez la documentation Braze pour Swift/iOS avant de compter sur une réactivation immédiate.

Événements

Abonnez-vous avec Braze.addListener(event, callback). L’appel renvoie un objet d’abonnement ; appelez .remove() sur cet objet pour arrêter l’écoute.

Configurer un écouteur :

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

Supprimer l’écouteur :

1

subscription.remove();

Dans un composant React, stockez l’abonnement et appelez .remove() lors du nettoyage (par exemple, dans la valeur de retour d’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();
}, []);

Notes d’intégration

• Expo : utilisez le plugin Braze Expo pour éviter, dans la mesure du possible, le câblage natif manuel.
• Nouvelle architecture / Turbo Modules : pris en charge dans les versions récentes du plugin. Si vous effectuez une migration, suivez le guide du développeur ainsi que les exemples de paramètres AppDelegate et Gradle.
• Confidentialité (iOS) : des méthodes telles que updateTrackingPropertyAllowList prennent en charge la configuration liée au manifeste de confidentialité. Consultez la page Manifeste de confidentialité Swift.

- Jest : simulez (mock) les modules natifs de react-native ou le module Turbo de Braze. Les tests unitaires ne sont pas publiés dans ce dépôt.

Prise en charge des versions

Remarque

Ce SDK a été testé avec la version 0.88.0 de React Native.

Le tableau suivant répertorie les versions de React Native prises en charge pour chaque version du plugin Braze.

Respectez également les exigences des SDK natifs :

• Informations sur les versions du SDK Android
• Informations sur les versions du SDK Swift

Plugin Expo de Braze

Pour les workflows gérés par Expo, consultez le dépôt du plugin Expo de Braze.

Exemple d’application

BrazeProject dans ce dépôt est un exemple complet (gestion des utilisateurs, Content Cards, feature flags, bannières, etc.).

1
2
3

cd BrazeProject/
yarn install
npx react-native start

iOS (depuis BrazeProject) :

1
2

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

Utilisez RCT_NEW_ARCH_ENABLED=0 pod install si vous avez besoin de l’ancienne architecture.

Android (depuis BrazeProject) :

1

npx react-native run-android

Débogage et résolution des problèmes

Pendant le développement, activez la journalisation Braze dans la configuration native pour que le SDK écrive dans la console système (Xcode / Logcat Android). Vous pourrez ainsi vérifier l’initialisation, les changements d’utilisateur et la distribution des événements.

• iOS — Dans la closure configure transmise à BrazeReactInitializer.configure, définissez config.logger.level = .debug (ou .info). Réduisez ou désactivez ce niveau en production pour que les logs ne soient pas visibles par les utilisateurs.
• Android — Utilisez la ressource com_braze_logger_initial_log_level dans braze.xml ou définissez l’équivalent sur BrazeConfig.Builder (voir BrazeConfigurationProvider). Utilisez un niveau moins détaillé ou supprimez ce paramètre avant la publication.

Pour une résolution des problèmes plus approfondie (réseau, session ou comportement des campagnes), consultez le guide du développeur React Native de Braze et la documentation des SDK natifs (Swift · Android).

Ressources supplémentaires

• Guide du développeur Braze — React Native
• Notifications push — React Native
• Dépôt GitHub
• Package npm

Contact

Pour toute question, contactez le support technique de Braze.

Pour en savoir plus sur le dépôt et consulter des exemples de projets, rendez-vous sur https://github.com/braze-inc/braze-react-native-sdk.