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 umschließt 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 in der 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 können Sie bei Bedarf weitere SDK-Methoden aufrufen (z. B. changeUser, logCustomEvent).

Was Sie tun können

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

Voraussetzungen

• Braze-Konto mit App-API-Schlüssel und SDK-Endpunkt
• React Native-Entwicklungsumgebung (React Native-Umgebungseinrichtung)
• iOS: Xcode, CocoaPods (cd ios && pod install)
• Android: Android Studio / Gradle; Kotlin-Gradle-Plugin gemäß den Anforderungen Ihres React Native-Templates
• Push (falls verwendet): FCM (Android) und APNs (iOS) gemäß der Push-Dokumentation

Informationen zu den Zugangsdaten im Dashboard finden Sie in der Integrationsübersicht.

Installation

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

Schnellstart

Dieser Abschnitt zeigt die minimale Einrichtung, die zur Initialisierung des Braze React Native SDK erforderlich ist.

1. Installieren Sie das npm-Paket (unter Installation).
2. Schließen Sie die native Einrichtung für Android und iOS ab (Konfiguration, Berechtigungen, Push falls erforderlich).
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-Typisierungen sind im Paket enthalten (src/index.d.ts auf GitHub).

Ein erneuter Aufruf von Braze.initialize mit anderen Zugangsdaten beendet die aktuelle Instanz und erstellt sie neu, sodass eine Re-Initialisierung während der Sitzung unterstützt wird.

Native Einrichtung

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

Android

• Fügen Sie das Kotlin-Gradle-Plugin in Ihre Root-Datei build.gradle ein, falls Ihr Template es noch nicht enthält (die Versionen hängen von Ihrer React Native-Version ab).
• Fügen Sie eine braze.xml-Ressourcendatei unter res/values mit Ihrer Konfiguration hinzu. Aktivieren Sie die verzögerte Initialisierung, damit das SDK auf den Aufruf von Braze.initialize() aus JavaScript wartet, bevor es startet. Weitere Konfigurationswerte (Push, Sitzungs-Timeout usw.) werden weiterhin aus dieser Datei gelesen und zum Zeitpunkt der Initialisierung angewendet.
• Stellen Sie sicher, dass grundlegende Berechtigungen wie INTERNET und ACCESS_NETWORK_STATE in AndroidManifest.xml vorhanden sind.
• Schließen Sie für Push die FCM-Integration sowie alle Braze-spezifischen Sender-ID-/Registrierungs-Flags ab, die in der Dokumentation beschrieben sind.

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 über Braze.initialize(apiKey, endpoint) aus JavaScript ü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, Sitzungen 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 der Erstellung, für Einrichtungsschritte, die die Instanz erfordern (z. B. Speichern einer Referenz, Festlegen von Delegates).

Hinweis

** BrazeReactInitializer.configure ist eine Swift-first-API, die das veraltete BrazeReactBridge.initBraze(_:) ersetzt. Sie behebt außerdem ein Swift-Typauflösungsproblem 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 befinden sich in XML; BrazeConfig.Builder kann sie beim Start überschreiben. Die maßgebliche Liste der Schlüssel und Typen finden Sie im Android-SDK-Integrationsleitfaden und in BrazeConfigurationProvider (jede Kotlin-Eigenschaft entspricht dokumentierten com_braze_*-Ressourcen).

Häufig verwendete Einträge:

iOS (Braze.Configuration)

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

Die React Native Bridge setzt bei der Initialisierung React-spezifische api.sdkFlavor-/SDK-Metadaten; überschreiben Sie diese nicht, es sei denn, die Braze-Dokumentation weist Sie dazu an.

JavaScript / TypeScript API

Der Standardexport 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.

Kernfunktionen

Nutzer:innenverwaltung

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 diese Funktion im Dashboard aktiviert ist.

In-App-Nachrichten

• Mit der Standard-Braze-UI 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 dann Impressionen/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);

Warten Sie auf Aktualisierungen mit Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, ...).

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 RN Linking zu vermeiden. Dafür sind native Hooks erforderlich (BrazeReactUtils auf iOS, BrazeReactUtils.populateInitialPushPayloadFromIntent auf Android), wie in den TypeScript-Dokumentationskommentaren und der Beispiel-App beschrieben.
• Braze.addListener(Braze.Events.PUSH_NOTIFICATION_EVENT, ...) ist laut den öffentlichen Typisierungen 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 Typisierungen).

Datenverwaltung und SDK-Status

changeUser teilt Braze lediglich mit, welcher Nutzer-ID neue Aktivitäten zugeordnet werden sollen. Es werden dabei keine zwischengespeicherten SDK-Daten auf dem Gerät gelöscht. Es gibt keine separate „Logout“-API: Wenn Sie eine klassische Abmeldung benötigen (lokalen Braze-Status löschen, damit 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ändiger lokaler Reset.

1
2
3
Braze.wipeData();
Braze.disableSDK();
Braze.enableSDK();

wipeData() — Löscht die lokalen Braze-Daten für diese Installation (zwischengespeicherter Nutzer-/Sitzungs-/Kartenstatus, Push-Token-Zuordnung usw.). Verwenden Sie diese Methode für Abmeldungsverhalten, wenn Sie den bisherigen Braze-Status der vorherigen Nutzer:innen nicht auf dem Gerät belassen möchten, sowie für „Meine Daten auf diesem Gerät löschen“, QA-Resets ohne Neuinstallation oder strikte Datenschutz-Abläufe. changeUser allein führt diese Bereinigung nicht durch – es legt lediglich fest, welche Nutzer-ID neue Events erhält. Unter iOS kann das Verhalten von Android abweichen (z. B. bei der Interaktion mit dem deaktivierten SDK-Status); konsultieren Sie die nativen Braze-Dokumentationen, wenn Sie dies in der Produktion einsetzen.

disableSDK() — Stoppt den Betrieb des SDK (keine Datenerfassung/-weiterleitung wie konfiguriert). Verwenden Sie diese Methode für Opt-out-Schalter der Nutzer:innen, eingeschränkte Modi (Compliance, Kindersicherung) oder Debugging ohne die Abhängigkeit zu entfernen.

enableSDK() — Aktiviert das SDK nach disableSDK() wieder. Unter iOS wird die erneute Aktivierung möglicherweise erst beim nächsten App-Start wirksam. Prüfen Sie in der Braze Swift/iOS-Dokumentation, ob Sie sich auf eine sofortige Reaktivierung verlassen können.

Events

Abonnieren Sie Events mit Braze.addListener(event, callback). Der Aufruf gibt ein Abonnement-Objekt zurück. Rufen Sie .remove() darauf auf, um das Lauschen 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();

In einer React-Komponente speichern Sie das Abonnement und rufen .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();
}, []);

Hinweise zur Integration

• Expo: Verwenden Sie nach Möglichkeit das Braze Expo Plugin, um manuelle native Verdrahtung zu vermeiden.
• New Architecture / Turbo Modules: Wird in aktuellen Plugin-Versionen unterstützt. Befolgen Sie den Entwicklerleitfaden und die Beispiel-Einstellungen für AppDelegate / Gradle, wenn Sie migrieren.

• 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 react-native-Module oder das Braze-Turbo-Modul (Muster finden Sie in __tests__/jest.setup.js in diesem Repository).

Versionsunterstützung

Hinweis

Dieses SDK wurde mit React Native Version 0.85.3 getestet.

Die folgende Tabelle listet unterstützte React Native Versionen nach Braze-Plugin-Release auf.

Beachten Sie auch die Anforderungen der nativen SDKs:

• Android SDK – Versionsinformationen
• Swift SDK – Versionsinformationen

Braze Expo Plugin

Für Expo-verwaltete Workflows siehe das Braze Expo Plugin Repository.

Beispiel-App

BrazeProject in diesem Repository ist ein vollständiges Beispiel (Nutzer:innenverwaltung, 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 das Braze-Logging in der nativen Konfiguration während der Entwicklung, damit das SDK in die Systemkonsole schreibt (Xcode / Android Logcat). Dies hilft bei der Überprüfung der Initialisierung, von Nutzer:innen-Änderungen und der Event-Zustellung.

• iOS — Setzen Sie in der configure-Closure, die an BrazeReactInitializer.configure übergeben wird, config.logger.level = .debug (oder .info). Reduzieren oder deaktivieren Sie dies in der Produktion, damit Logs für Nutzer:innen nicht sichtbar sind.
• Android — Verwenden Sie die Ressource com_braze_logger_initial_log_level in braze.xml oder setzen Sie den entsprechenden Wert über BrazeConfig.Builder (siehe BrazeConfigurationProvider). Verwenden Sie vor der Veröffentlichung ein weniger ausführliches Log-Level oder entfernen Sie die Überschreibung.

Für eine tiefergehende Fehlerbehebung (Netzwerk-, Sitzungs- oder Campaign-Verhalten) lesen Sie den Braze React Native-Entwicklerleitfaden und die nativen SDK-Dokumentationen (Swift · Android).

Weitere Ressourcen

• Braze-Entwicklerleitfaden — React Native
• Push-Benachrichtigungen — React Native
• GitHub-Repository
• npm-Paket

Kontakt

Bei Fragen wenden Sie sich an den technischen Support von Braze.

Für Repository-Details und Beispielprojekte siehe https://github.com/braze-inc/braze-react-native-sdk.