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.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 컴포넌트에서는 구독을 저장하고 클린업 시 .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를 참조하세요.