React Native SDK Repository-Leitfaden

Über das Braze React Native SDK

Das Braze React Native SDK verbindet Ihre iOS- und Android-Apps mit Braze: Nutzerprofile, Messaging-Oberflächen, Analytics und Feature-Flags. Es kapselt das native Braze Swift SDK und das Braze Android SDK hinter einer JavaScript-API.

Die Initialisierung erfolgt über JavaScript: Sie richten die native Konfiguration (Push, Logging, Delegates) in den Android-Ressourcen und im iOS-AppDelegate ein und rufen dann Braze.initialize(apiKey, endpoint) aus JavaScript auf, um das SDK zu starten. So haben Sie die volle Kontrolle darüber, wann das SDK initialisiert wird und mit welchen Zugangsdaten. Nach der Initialisierung rufen Sie bei Bedarf weitere SDK-Methoden auf (zum Beispiel changeUser, logCustomEvent).

Was Sie tun können

• Nutzerverwaltung: Nutzer:innen identifizieren sowie Profilfelder, angepasste Attribute, Aliase und Abo-Gruppen festlegen
• In-App-Nachrichten: Standard-UI von Braze oder angepasste Verarbeitung über Abonnements und Logging-APIs
• Content Cards: Standard-Feed-UI oder Karten abrufen und Ihre eigene UI erstellen
• Banner: Platzierungsbasierte HTML-Banner, einschließlich BrazeBannerView
• Push-Benachrichtigungen: Berechtigungsabfragen, Token-Registrierung, Payload-Listener (siehe Plattformhinweise unten)
• Feature-Flags: Aktualisieren, Eigenschaften lesen, Impressionen protokollieren
• Analytics: Angepasste Events, Käufe, sofortiges Flushen
• SDK-Steuerung: SDK aktivieren/deaktivieren, lokale Daten löschen, Signaturen für die SDK-Authentifizierung

Voraussetzungen

• Braze-Konto mit App-API-Schlüssel und SDK-Endpunkt
• React Native-Entwicklungsumgebung (React Native-Umgebung einrichten)
• iOS: Xcode, CocoaPods (cd ios && pod install)
• Android: Android Studio / Gradle; Kotlin-Gradle-Plugin, wie von Ihrem React Native-Template gefordert
• Push (falls verwendet): Einrichtung von FCM (Android) und APNs (iOS) gemäß der Push-Dokumentation

Informationen dazu, wo Sie Ihre Zugangsdaten im Dashboard finden, erhalten Sie in der Übersicht zur Integration.

Installation

1
2
3

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

Schnellstart

In diesem Abschnitt sehen Sie die minimale Einrichtung, die für die Initialisierung des Braze React Native SDK erforderlich ist.

1. Installieren Sie das npm-Paket (siehe oben).
2. Schließen Sie die native Einrichtung für Android und iOS ab (Konfiguration, Berechtigungen und bei Bedarf Push).
3. Initialisieren Sie das SDK über JavaScript und beginnen Sie mit der Nutzung:

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

TypeScript-Typdefinitionen sind im Paket enthalten (src/index.d.ts auf GitHub).

Wenn Sie Braze.initialize erneut mit anderen Zugangsdaten aufrufen, wird die aktuelle Instanz beendet und neu erstellt. So ist eine erneute Initialisierung während einer laufenden Session möglich.

Native Einrichtung

Maßgebliche Quelle: Schritt-für-Schritt-Anleitungen, Änderungen an Gradle/CocoaPods und die vollständige Liste der Android-XML-Schlüssel finden Sie im Braze React Native Entwickler:innen-Leitfaden. Die folgenden Snippets sind minimale Beispiele.

Android

• Fügen Sie das Kotlin Gradle Plugin in Ihrer Root-Datei build.gradle hinzu, falls Ihr Template es noch nicht enthält (die Versionen hängen von Ihrer React-Native-Version ab).
• Fügen Sie eine Ressourcendatei braze.xml in res/values mit Ihrer Konfiguration hinzu. Aktivieren Sie die verzögerte Initialisierung, damit das SDK vor dem Start auf Braze.initialize() aus JavaScript wartet. Andere Konfigurationswerte (Push, Session-Timeout usw.) werden weiterhin aus dieser Datei gelesen und bei der Initialisierung angewendet.
• Stellen Sie grundlegende Berechtigungen wie INTERNET und ACCESS_NETWORK_STATE in AndroidManifest.xml sicher.
• Schließen Sie für Push die FCM-Integration ab und setzen Sie alle in der Dokumentation beschriebenen Braze-spezifischen Sender-ID- bzw. Registrierungs-Flags.

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>

Hinweis

** Der API-Schlüssel und der Endpunkt werden nicht mehr in braze.xml festgelegt – sie werden aus JavaScript über Braze.initialize(apiKey, endpoint) übergeben.

iOS

1

cd ios && pod install

Verwenden Sie BrazeReactInitializer.configure in Ihrem AppDelegate, um die native Konfiguration zu registrieren. Die von Ihnen bereitgestellten Closures werden gespeichert und später angewendet, wenn Braze.initialize(apiKey, endpoint) aus JavaScript aufgerufen wird.

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

• configure-Closure: Erhält eine Braze.Configuration und ermöglicht es Ihnen, native Konfigurationseigenschaften festzulegen (Logging, Push, Sessions usw.). Der API-Schlüssel und der Endpunkt werden aus JavaScript bereitgestellt – Sie legen sie hier nicht fest.
• postInitialization-Closure (optional): Erhält die aktive Braze-Instanz nach ihrer Erstellung, für Einrichtungsschritte, die die Instanz benötigen (z. B. Speichern einer Referenz, Festlegen von Delegates).

Hinweis

** BrazeReactInitializer.configure ist eine Swift-first-API, die das veraltete BrazeReactBridge.initBraze(_:) ersetzt. Außerdem behebt sie ein Problem bei der Swift-Typauflösung mit Braze.Configuration in der Objective-C-Bridge.

Konfigurationsreferenz

In React Native ist die Konfiguration nativ: Android liest res/values/braze.xml, und iOS verwendet Closures, die über BrazeReactInitializer.configure registriert werden. Beide werden angewendet, wenn Braze.initialize(apiKey, endpoint) aus JavaScript aufgerufen wird.

Android (braze.xml)

Standardwerte sind im XML hinterlegt; BrazeConfig.Builder kann sie beim Start überschreiben. Die maßgebliche Liste der Schlüssel und Typen finden Sie im Leitfaden zur Android-SDK-Integration und in BrazeConfigurationProvider (jede Kotlin-Eigenschaft entspricht dokumentierten com_braze_*-Ressourcen).

Häufig verwendete Einträge:

iOS (Braze.Configuration)

Legen Sie native Konfigurationseigenschaften in der configure-Closure fest, die an BrazeReactInitializer.configure übergeben wird. Die Closure erhält eine Braze.Configuration-Instanz – API-Schlüssel und Endpunkt werden automatisch aus dem JavaScript-Aufruf Braze.initialize gesetzt. Alle Details: Braze.Configuration und die verschachtelten Typen api, push, logger, location.

Die React-Native-Bridge setzt bei der Initialisierung React-spezifische api.sdkFlavor- bzw. SDK-Metadaten; überschreiben Sie diese nur, wenn die Braze-Dokumentation Sie dazu anweist.

JavaScript / TypeScript API

Der Standard-Export des Pakets ist die Klasse Braze mit statischen Methoden (zum Beispiel Braze.changeUser, Braze.logPurchase). Konstanten wie Braze.Events, Braze.Genders und Braze.NotificationSubscriptionTypes sind an denselben Export angehängt.

Kern-Features

Nutzerverwaltung

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

Optionale SDK-Authentifizierung: Übergeben Sie eine Signatur als zweites Argument an changeUser oder rufen Sie Braze.setSdkAuthenticationSignature(signature) auf, wenn die Funktion im Dashboard aktiviert ist.

In-App-Nachrichten

• Wenn Sie die Standard-UI von Braze verwenden, folgen Sie der Dokumentation zu In-App-Nachrichten. In der Regel müssen Sie subscribeToInAppMessage nicht aufrufen, nur um die Standard-UI anzuzeigen.
• Für eine angepasste Verarbeitung abonnieren Sie mit useBrazeUI: false und protokollieren Sie anschließend Impressionen und Klicks nach Bedarf:

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

Mit Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, ...) können Sie auf Aktualisierungen warten.

Banner

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

Push-Benachrichtigungen

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: Verwenden Sie diese Methode, wenn die App über eine Benachrichtigung geöffnet wird, um Race-Conditions mit Linking in React Native zu vermeiden. Dafür ist auf jeder Plattform eine native Einrichtung erforderlich.
  • iOS mit Launch-Optionen des App-Delegates: Rufen Sie populateInitialPayloadFromLaunchOptions: auf BrazeReactUtils in application:didFinishLaunchingWithOptions: auf.
  • iOS mit Scene-Lebenszyklus: Rufen Sie populateInitialPayloadFromNotificationResponse: auf BrazeReactUtils in scene:willConnectToSession:options: auf.
  • Android: Rufen Sie BrazeReactUtils.populateInitialPushPayloadFromIntent in MainActivity.onCreate() auf.
• Braze.addListener(Braze.Events.PUSH_NOTIFICATION_EVENT, ...) ist laut den öffentlichen Typdefinitionen nur für Android verfügbar.

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

Analytics und Käufe

1
2
3

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

Hinweis: logPurchase erwartet den Preis als String (siehe Typdefinitionen).

Datenverwaltung und SDK-Status

changeUser teilt Braze lediglich mit, welcher Nutzer-ID neue Aktivitäten zugeordnet werden sollen. Zwischengespeicherte SDK-Daten auf dem Gerät werden dabei nicht gelöscht. Es gibt keine separate „Logout“-API: Wenn Sie eine klassische Abmeldung benötigen (lokalen Braze-Status löschen, sodass das zwischengespeicherte Profil, die Nachrichten und Token der vorherigen Nutzer:innen auf dieser Installation entfernt werden), verwenden Sie in der Regel wipeData(). Dies ist ein vollständiges lokales Zurücksetzen.

1
2
3

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

wipeData(): Löscht die lokalen Braze-Daten dieser Installation (zwischengespeicherter Nutzer-, Sitzungs- und Kartenstatus, Push-Token-Zuordnung usw.). Verwenden Sie diese Methode für abmeldungsähnliches Verhalten, wenn der Braze-Status der vorherigen Nutzer:innen nicht auf dem Gerät verbleiben darf, sowie für „Meine Daten auf diesem Gerät löschen“, QA-Resets ohne Neuinstallation oder strenge Datenschutz-Abläufe. changeUser allein führt diese Bereinigung nicht durch, sondern legt nur fest, welche Nutzer-ID neue Events erhält. Unter iOS kann das Verhalten von Android abweichen (z. B. im Zusammenspiel mit dem deaktivierten SDK-Status). Lesen Sie die nativen Braze-Dokumentationen, wenn Sie dies in der Produktion einsetzen.

disableSDK(): Stoppt den Betrieb des SDK (keine Erfassung oder Weiterleitung gemäß Konfiguration). Verwenden Sie diese Methode für Opt-out-Schalter von Nutzer:innen, eingeschränkte Modi (Compliance, Kindereinstellungen) oder zum Debugging, ohne die Abhängigkeit zu entfernen.

enableSDK(): Schaltet das SDK nach disableSDK() wieder ein. Unter iOS wird die erneute Aktivierung möglicherweise erst beim nächsten App-Start wirksam. Prüfen Sie dies in der Braze-Dokumentation für Swift/iOS, bevor Sie sich auf eine sofortige Reaktivierung verlassen.

Events

Abonnieren Sie Events mit Braze.addListener(event, callback). Der Aufruf gibt ein Abo-Objekt zurück. Rufen Sie darauf .remove() auf, um das Abhören zu beenden.

Einen Listener einrichten:

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

Den Listener entfernen:

1

subscription.remove();

Speichern Sie in einer React-Komponente das Abo-Objekt und rufen Sie .remove() in Ihrer Bereinigung auf (z. B. im Rückgabewert eines useEffect):

1
2
3
4
5
6

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

Integrationshinweise

• Expo: Verwenden Sie das Braze Expo Plugin, um manuelle native Verknüpfungen nach Möglichkeit zu vermeiden.
• New Architecture / Turbo Modules: Werden in aktuellen Plugin-Versionen unterstützt. Folgen Sie bei einer Migration dem Entwicklerleitfaden und den Beispieleinstellungen für AppDelegate / Gradle.
• Datenschutz (iOS): Methoden wie updateTrackingPropertyAllowList unterstützen die Konfiguration im Zusammenhang mit dem Privacy Manifest. Weitere Informationen finden Sie unter Swift Privacy Manifest.

- Jest: Mocken Sie native Module von react-native oder das Braze Turbo-Modul. Unit-Tests werden in diesem Repository nicht veröffentlicht.

Versionsunterstützung

Hinweis

Dieses SDK wurde mit React Native Version 0.88.0 getestet.

Die folgende Tabelle listet die unterstützten React Native-Versionen nach Release des Braze Plugins auf.

Beachten Sie außerdem die Anforderungen der nativen SDKs:

• Versionsinformationen zum Android SDK
• Versionsinformationen zum Swift SDK

Braze Expo-Plugin

Informationen zu Expo-verwalteten Workflows finden Sie im Repository des Braze Expo-Plugins.

Beispiel-App

BrazeProject in diesem Repository ist ein vollständiges Beispiel (Nutzerverwaltung, Content Cards, Feature-Flags, Banner usw.).

1
2
3

cd BrazeProject/
yarn install
npx react-native start

iOS (aus BrazeProject):

1
2

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

Verwenden Sie RCT_NEW_ARCH_ENABLED=0 pod install, wenn Sie die Legacy-Architektur benötigen.

Android (aus BrazeProject):

1

npx react-native run-android

Debugging und Fehlerbehebung

Aktivieren Sie während der Entwicklung das Braze-Logging in der nativen Konfiguration, damit das SDK in die Systemkonsole (Xcode / Android Logcat) schreibt. So können Sie die Initialisierung, Nutzerwechsel und die Zustellung von Events überprüfen.

• iOS – Setzen Sie in der configure-Closure, die an BrazeReactInitializer.configure übergeben wird, config.logger.level = .debug (oder .info). Reduzieren oder deaktivieren Sie das Logging in der Produktion, damit die Logs für Nutzer:innen nicht sichtbar sind.
• Android – Verwenden Sie die Ressource com_braze_logger_initial_log_level in braze.xml oder legen Sie die entsprechende Einstellung in BrazeConfig.Builder fest (siehe BrazeConfigurationProvider). Verwenden Sie vor dem Release eine weniger ausführliche Log-Stufe oder entfernen Sie die Überschreibung.

Weitere Informationen zur Fehlerbehebung (Netzwerk-, Session- oder Kampagnenverhalten) finden Sie im Braze React Native Entwicklerhandbuch und in der Dokumentation der nativen SDKs (Swift · Android).

Zusätzliche Ressourcen

• Braze-Entwicklerhandbuch – React Native
• Push-Benachrichtigungen – React Native
• GitHub-Repository
• npm-Paket

Kontakt

Wenn Sie Fragen haben, wenden Sie sich an den technischen Support von Braze.

Details zum Repository und Beispielprojekte finden Sie unter https://github.com/braze-inc/braze-react-native-sdk.