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認証署名

前提条件

• アプリ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

クイックスタート

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.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.getContentCards();
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コンポーネントでは、サブスクリプションを保存し、クリーンアップ時に.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.83.0でテストされています。

ネイティブ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を参照）。リリース前に冗長でないレベルを使用するか、オーバーライドを削除してください。

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

その他のリソース

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

お問い合わせ

ご質問がある場合は、[email protected]までお問い合わせください。

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