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は、非推奨の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

パッケージのデフォルトエクスポートは、staticメソッド（例：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認証（任意）：ダッシュボードで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：通知からアプリが開かれたときに、React Nativeの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モジュールをモックします。ユニットテストはこのリポジトリでは公開されていません。

バージョンサポート

注

このSDKはReact Nativeバージョン 0.87.1 でテストされています。

以下の表は、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を参照してください。