React Native SDKリポジトリガイド

Braze React Native SDKについて

Braze React Native SDKは、iOSおよびAndroidアプリをBrazeに接続します。ユーザープロファイル、メッセージング画面、分析、フィーチャーフラグに対応しています。ネイティブのBraze Swift SDKとBraze Android SDKをJavaScript APIでラップしています。

初期化はJavaScript主導です。 ネイティブ設定（プッシュ、ログ、デリゲート）をAndroidリソースとiOSのAppDelegateで行い、JavaScriptからBraze.initialize(apiKey, endpoint)を呼び出してSDKを起動します。これにより、SDKの初期化タイミングと使用する認証情報を完全にコントロールできます。初期化後、必要に応じて他のSDKメソッド（例：changeUser、logCustomEvent）を呼び出します。

できること

• ユーザー管理: ユーザーの識別、プロファイルフィールドの設定、カスタム属性、エイリアス、購読グループの管理
• アプリ内メッセージ: デフォルトのBraze UIまたは購読やログAPIを使ったカスタムハンドリング
• Content Cards: デフォルトのフィードUI、またはカードを取得して独自のUIを構築
• バナー: プレースメントベースのHTMLバナー（BrazeBannerViewを含む）
• プッシュ通知: 権限プロンプト、トークン登録、ペイロードリスナー。プラットフォーム固有の注意事項については、ネイティブセットアップを参照してください。
• フィーチャーフラグ: リフレッシュ、プロパティの読み取り、インプレッションの記録
• 分析: カスタムイベント、購入、即時フラッシュ
• SDKコントロール: SDKの有効化/無効化、ローカルデータの消去、SDK認証署名

前提条件

• Brazeアカウント（アプリAPIキーとSDKエンドポイントが必要）
• React Native開発環境（React Native環境セットアップ）
• iOS：Xcode、CocoaPods（cd ios && pod install）
• Android：Android Studio / Gradle、React Nativeテンプレートで必要なKotlin Gradleプラグイン
• プッシュ（使用する場合）：FCM（Android）およびAPNs（iOS）のセットアップ（プッシュ通知のドキュメントを参照）

ダッシュボードでの認証情報の場所については、統合の概要を参照してください。

インストール

1
2
3

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

クイックスタート

このセクションでは、Braze React Native SDKを初期化するために必要な最小限の設定を説明します。

1. インストールでnpmパッケージをインストールします。
2. AndroidとiOSのネイティブセットアップを完了します（設定、権限、必要に応じてプッシュ）。
3. JavaScriptからSDKを初期化して使用を開始します：

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の型定義はパッケージに同梱されています（GitHubのsrc/index.d.ts）。

Braze.initializeを異なる認証情報で再度呼び出すと、現在のインスタンスが破棄されて再作成されるため、セッション中の再初期化がサポートされます。

ネイティブ設定

信頼できる情報源： ステップバイステップの画面、Gradle/CocoaPodsの変更、およびAndroid XMLキーの完全なリストは、Braze React Nativeデベロッパーガイドにあります。以下のスニペットは最小限の例です。

Android

• テンプレートにまだ含まれていない場合は、ルートのbuild.gradleにKotlin Gradleプラグインを追加します（バージョンはReact Nativeのバージョンに依存します）。
• res/valuesに設定を含むbraze.xmlリソースファイルを追加します。遅延初期化を有効にして、SDKがJavaScriptからのBraze.initialize()を待ってから開始するようにします。その他の設定値（プッシュ、セッションタイムアウトなど）は引き続きこのファイルから読み取られ、初期化時に適用されます。
• AndroidManifest.xmlでINTERNETやACCESS_NETWORK_STATEなどの基本的な権限を確認します。
• プッシュ通知については、FCMの統合と、ドキュメントに記載されているBraze固有の送信者ID／登録フラグを完了してください。

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>

注

** APIキーとエンドポイントはbraze.xmlでは設定しなくなりました。JavaScriptからBraze.initialize(apiKey, endpoint)経由で渡されます。

iOS

1

cd ios && pod install

AppDelegateでBrazeReactInitializer.configureを使用して、ネイティブ設定を登録します。提供したクロージャは保存され、JavaScriptからBraze.initialize(apiKey, endpoint)が呼び出されたときに適用されます。

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クロージャ：Braze.Configurationを受け取り、ネイティブ設定プロパティ（ログ、プッシュ、セッションなど）を設定できます。APIキーとエンドポイントはJavaScriptから提供されるため、ここでは設定しません。
• postInitializationクロージャ（オプション）：作成後のライブBrazeインスタンスを受け取り、インスタンスが必要な設定（例：参照の保存、デリゲートの設定）に使用します。

注

** BrazeReactInitializer.configureは、非推奨のBrazeReactBridge.initBraze(_:)に代わるSwiftファーストAPIです。また、Objective-CブリッジにおけるBraze.ConfigurationのSwift型解決の問題も解消します。

設定リファレンス

React Nativeでは、設定はネイティブで行います。Androidはres/values/braze.xmlを読み取り、iOSはBrazeReactInitializer.configureを介して登録されたクロージャーを使用します。いずれもJavaScriptからBraze.initialize(apiKey, endpoint)が呼び出された際に適用されます。

Android（braze.xml）

デフォルト値はXMLに定義されています。BrazeConfig.Builderを使用すると、起動時にこれらを上書きできます。キーと型の正式なリストは、Android SDK統合ガイドおよびBrazeConfigurationProviderにあります（各Kotlinプロパティは、ドキュメント化されたcom_braze_*リソースに対応しています）。

よく使用されるエントリ：

iOS（Braze.Configuration）

BrazeReactInitializer.configureに渡すconfigureクロージャー内でネイティブの設定プロパティを設定します。クロージャーはBraze.Configurationインスタンスを受け取ります。APIキーとエンドポイントは、JavaScriptのBraze.initialize呼び出しから自動的に設定されます。詳細については、Braze.Configurationおよびネストされた型（api、push、logger、location）を参照してください。

React Nativeブリッジは初期化時にReact固有のapi.sdkFlavor／SDKメタデータを設定します。Brazeのドキュメントで指示がない限り、これらを上書きしないでください。

JavaScript / TypeScript API

パッケージのデフォルトエクスポートは、静的メソッドを持つBrazeクラスです（例：Braze.changeUser、Braze.logPurchase）。Braze.Events、Braze.Genders、Braze.NotificationSubscriptionTypesなどの定数も同じエクスポートに付属しています。

コア機能

ユーザー管理

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

オプションのSDK認証：changeUserの第2引数としてシグネチャを渡すか、ダッシュボードで有効にした場合はBraze.setSdkAuthenticationSignature(signature)を呼び出します。

アプリ内メッセージ

• デフォルトのBraze UIを使用する場合は、アプリ内メッセージのドキュメントに従ってください。デフォルトUIを表示するだけであれば、通常subscribeToInAppMessageを呼び出す必要はありません。
• カスタム処理の場合は、useBrazeUI: falseでサブスクライブし、必要に応じてインプレッション/クリックを記録します：

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

Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, ...)で更新をリッスンします。

バナー

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

プッシュ通知

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：通知からアプリが開かれた際にRNのLinkingの競合を回避するために使用します。iOSではBrazeReactUtils、AndroidではBrazeReactUtils.populateInitialPushPayloadFromIntentのネイティブフックが必要です。TypeScriptのドキュメントコメントとサンプルアプリに詳細が記載されています。
• Braze.addListener(Braze.Events.PUSH_NOTIFICATION_EVENT, ...)は、公開の型定義によるとAndroid専用です。

フィーチャーフラグ

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

分析と購入

1
2
3

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

注意：logPurchaseはpriceを文字列として受け取ります（型定義を参照してください）。

データ管理とSDKの状態

changeUserは、新しいアクティビティをどのユーザーIDに紐付けるかをBrazeに伝えるだけです。デバイス上のキャッシュされたSDKデータをクリアするわけではありません。個別の「ログアウト」APIはありません。従来のサインアウト（前のユーザーのキャッシュされたプロファイル、メッセージ、トークンをこのインストールから消去するためにローカルのBraze状態をクリアする）が必要な場合は、通常wipeData()を使用します。これは完全なローカルリセットです。

1
2
3

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

wipeData() — このインストールのBrazeのローカルデータ（キャッシュされたユーザー/セッション/カードの状態、プッシュトークンの紐付けなど）をクリアします。前のユーザーのBraze状態をデバイスに残してはいけない場合のサインアウトスタイルの動作、「このデバイスのデータを削除」、再インストールなしのQAリセット、または厳格なプライバシーフローに使用します。changeUser単体ではそのクリーンアップを実行しません。新しいイベントを受け取るユーザーIDを設定するだけです。iOSでは、動作がAndroidと異なる場合があります（例：SDK無効化状態との相互作用）。本番環境で使用する場合は、Brazeのネイティブドキュメントを参照してください。

disableSDK() — SDKの動作を停止します（設定に基づくデータ収集/転送を行いません）。ユーザーのオプトアウトトグル、制限モード（コンプライアンス、キッズ設定）、または依存関係を削除せずに行うデバッグに使用します。

enableSDK() — disableSDK()の後にSDKを再度有効にします。iOSでは、再有効化が次のアプリ起動まで適用されない場合があります。即時の再有効化に依存する前に、Braze Swift/iOSのドキュメントで確認してください。

イベント

Braze.addListener(event, callback) でサブスクライブします。この呼び出しはサブスクリプションオブジェクトを返します。リスニングを停止するには、そのオブジェクトの .remove() を呼び出します。

リスナーの設定：

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

リスナーの削除：

1

subscription.remove();

Reactコンポーネントでは、サブスクリプションを保存し、クリーンアップ時に .remove() を呼び出します（例：useEffect のreturn内）。

1
2
3
4
5
6

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

統合に関する注意事項

• Expo: 手動のネイティブ設定を可能な限り避けるために、Braze Expoプラグインを使用してください。
• New Architecture / Turbo Modules: 最新のプラグインバージョンでサポートされています。移行する場合は、開発者ガイドおよびサンプルのAppDelegate / Gradle設定に従ってください。
• プライバシー (iOS): updateTrackingPropertyAllowListなどのメソッドは、プライバシーマニフェスト関連の設定をサポートしています。詳細については、Swiftプライバシーマニフェストを参照してください。

- Jest: react-nativeのネイティブモジュールまたはBraze Turboモジュールをモックします（パターンについては、このリポジトリの__tests__/jest.setup.jsを参照してください）。

バージョンサポート

注

このSDKはReact Nativeバージョン0.85.3でテスト済みです。

以下の表は、BrazeプラグインリリースごとにサポートされるReact Nativeバージョンを示しています。

ネイティブSDKの要件も確認してください。

• Android SDKバージョン情報
• Swift SDKバージョン情報

Braze Expoプラグイン

Expo管理ワークフローについては、Braze Expoプラグインリポジトリを参照してください。

サンプルアプリ

このリポジトリのBrazeProjectは、完全なサンプル（ユーザー管理、Content Cards、フィーチャーフラグ、バナーなど）です。

1
2
3

cd BrazeProject/
yarn install
npx react-native start

iOS（BrazeProjectから）：

1
2

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

レガシーアーキテクチャが必要な場合は、RCT_NEW_ARCH_ENABLED=0 pod installを使用してください。

Android（BrazeProjectから）：

1

npx react-native run-android

デバッグとトラブルシューティング

開発中はネイティブ設定でBrazeのログを有効にし、SDKがシステムコンソール（Xcode / Android Logcat）に書き込むようにします。これにより、初期化、ユーザーの変更、イベント配信を確認できます。

• iOS — BrazeReactInitializer.configureに渡すconfigureクロージャ内で、config.logger.level = .debug（または.info）を設定します。本番環境ではログがユーザーに表示されないよう、レベルを下げるか無効にしてください。
• Android — braze.xmlのcom_braze_logger_initial_log_levelリソースを使用するか、BrazeConfig.Builderで同等の設定を行います（BrazeConfigurationProviderを参照）。リリース前に、冗長でないレベルを使用するか、オーバーライドを削除してください。

より詳細なトラブルシューティング（ネットワーク、セッション、キャンペーンの動作）については、Braze React Native開発者ガイドおよびネイティブSDKドキュメント（Swift · Android）を参照してください。

その他のリソース

• Braze開発者ガイド — React Native
• プッシュ通知 — React Native
• GitHubリポジトリ
• npmパッケージ

お問い合わせ

ご質問がある場合は、Brazeテクニカルサポートにお問い合わせください。

リポジトリの詳細とサンプルプロジェクトについては、https://github.com/braze-inc/braze-react-native-sdkを参照してください。