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 엔드포인트가 포함된 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 및 iOS 섹션의 스니펫은 최소한의 예시입니다.

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 클래스입니다(예: 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의 두 번째 인수로 서명을 전달하거나, 대시보드에서 활성화된 경우 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는 Braze에 새로운 활동을 어떤 사용자 ID에 귀속할지만 알려줍니다. 기기에 캐시된 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의 반환 함수):

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 참조). 릴리스 전에 상세하지 않은 로그 수준을 사용하거나 오버라이드를 제거하세요.

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

추가 리소스

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

문의

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

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