React Native SDKリポジトリガイド

Braze React Native SDKについて

Braze React Native SDKは、iOSアプリとAndroidアプリをBrazeに接続し、ユーザープロファイル、メッセージングサーフェス、分析、フィーチャーフラグを利用できるようにします。このSDKは、ネイティブの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を構築
• バナー：BrazeBannerViewを含む、プレースメントベースのHTMLバナー
• プッシュ通知：権限プロンプト、トークン登録、ペイロードリスナー（ネイティブ設定のプラットフォームに関する注意事項を参照）
• フィーチャーフラグ：更新、プロパティの読み取り、インプレッションのログ記録
• 分析：カスタムイベント、購入、即時フラッシュ
• SDKコントロール：SDKの有効化/無効化、ローカルデータの消去、SDK認証の署名

前提条件

• アプリの API キーと SDKエンドポイントを持つ Braze アカウント
• 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 では設定しなくなりました。これらは Braze.initialize(apiKey, endpoint) を介して JavaScript から渡されます。

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 は Swift ファーストの API で、非推奨となった BrazeReactBridge.initBraze(_:) に代わるものです。また、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.changeUser、Braze.logPurchase）を持つBrazeクラスです。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との競合を避けるために使用します。TypeScriptのドキュメントコメントとサンプルアプリで説明されているとおり、ネイティブフック（iOSではBrazeReactUtils、AndroidではBrazeReactUtils.populateInitialPushPayloadFromIntent）が必要です。
• 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は価格を文字列として受け取ります（型定義を参照）。

データ管理と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コンポーネントでは、サブスクリプションを保存し、クリーンアップ処理（useEffectの戻り値など）で.remove()を呼び出します。

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 を参照してください。