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を構築
• バナー：BrazeBannerViewを含むプレースメントベースのHTMLバナー
• プッシュ通知：権限プロンプト、トークン登録、ペイロードリスナー（以下のプラットフォームに関する注意事項を参照）
• フィーチャーフラグ：更新、プロパティの読み取り、インプレッションの記録
• 分析：カスタムイベント、購入、即時フラッシュ
• 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リソースファイルを作成し、設定を記述します。遅延初期化を有効にして、JavaScriptからBraze.initialize()が呼び出されるまでSDKが待機するようにします。その他の設定値（プッシュ、セッションタイムアウトなど）は引き続きこのファイルから読み取られ、初期化時に適用されます。
• 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を参照してください。