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에서 설정하지 않으며, 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의 두 번째 인수로 서명을 전달하거나 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 모듈을 모의(mock) 처리합니다(패턴은 이 리포지토리의 __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 참조). 릴리스 전에는 상세하지 않은 로그 수준을 사용하거나 재정의를 제거하세요.

네트워크, 세션 또는 Campaign 동작과 관련된 심층적인 문제 해결은 Braze React Native 개발자 가이드와 네이티브 SDK 설명서(Swift · Android)를 참조하세요.

추가 리소스

• Braze 개발자 가이드 — React Native
• 푸시 알림 — React Native
• GitHub 리포지토리
• npm 패키지

문의

질문이 있으면 Braze 기술 지원팀에 문의하여 도움을 받으세요.

리포지토리 세부 정보와 샘플 프로젝트는 https://github.com/braze-inc/braze-react-native-sdk를 참조하세요.