React Native SDK

Monetai React Native SDK는 앱 내에서 다이나믹 프라이싱과 개인화된 오퍼를 직접 구현할 수 있도록 돕습니다. 이 가이드는 SDK 설치부터 초기화, 이벤트 수집, 다이나믹 프라이싱 구현까지 전 과정을 안내합니다.

사전 요구사항

React Native 0.73 이상
iOS: iOS 13.0 이상
Android: API Level 24 이상
- Android는 SDK 버전 0.2.9 버전부터 지원됩니다.
- Android Billing Client v7은 SDK 버전 0.3.0부터 사용됩니다.

SDK 설정

📌 이 섹션에서는 Monetai SDK를 설치하고, 다이나믹 프라이싱에 필요한 데이터를 수집하도록 구성하는 방법을 안내합니다.
모든 프로모션 기능을 원활하게 사용하려면, 아래의 세 가지 단계를 반드시 진행해 주세요.

1. SDK 설치

사용하시는 패키지 매니저를 이용해 프로젝트에 Monetai 패키지를 추가하세요.

yarn
npm

yarn add @hayanmind/monetai-react-native

npm install @hayanmind/monetai-react-native

iOS 추가 설정
iOS 프로젝트에 다음 명령어를 실행하여 네이티브 모듈을 설치합니다.

cd ios && pod install

앱 다시 빌드하기
SDK 설치가 끝나면, 변경사항을 적용하기 위해 앱을 다시 빌드해야 합니다.

iOS
Android

npx react-native run-ios

npx react-native run-android

2. SDK 초기화

앱이 시작될 때 SDK를 초기화합니다. App.js와 같은 최상위 컴포넌트에서 설정하는 것을 권장합니다.

import MonetaiSDK from "@hayanmind/monetai-react-native";

// 앱 시작 시 초기화
const initializeMonetai = async () => {
  try {
    const result = await MonetaiSDK.initialize({
      sdkKey: "YOUR_SDK_KEY", // Monetai 대시보드에서 발급받은 SDK 키
      userId: "USER_ID", // 앱 사용자의 User ID
      useStoreKit2: true, // iOS 15+ 기기에서 StoreKit2 사용 (권장)
    });

    console.log("Monetai SDK 초기화 완료:", result);
  } catch (error) {
    console.error("Monetai SDK 초기화 실패:", error);
  }
};

// App.js에서 호출
useEffect(() => {
  initializeMonetai();
}, []);

API Reference: MonetaiSDK.initialize()

매개변수 (Parameters)

파라미터	타입	설명
sdkKey	string	Monetai에서 발급받은 SDK 키 (설정 > SDK 연동)
userId	string	앱 사용자의 User ID (없을 경우 이메일, 디바이스 ID 등 고유 식별값 활용)
useStoreKit2	boolean?	StoreKit2 사용 여부 (iOS 전용, 기본값: `false`)

반환 값 (Return Value)

반환값	타입	설명
organizationId	number	조직 ID
platform	'react_native'	플랫폼 정보
version	string	SDK 버전
userId	string	설정된 사용자 ID

3. 사용자 이벤트 기록

정확한 AI 모델 빌딩을 위한 핵심 단계입니다. Monetai의 AI 모델은 앱에서 보내는 사용자 이벤트를 기반으로 행동을 분석하고, 구매 여부를 예측합니다. 이 데이터가 없으면 구매 예측 기능이 동작하지 않으므로, 반드시 필요한 과정입니다.

import MonetaiSDK from "@hayanmind/monetai-react-native";

// 기본 이벤트 로깅
await MonetaiSDK.logEvent({
  eventName: "app_in",
});

// 파라미터가 포함된 이벤트 로깅
await MonetaiSDK.logEvent({
  eventName: "screen_in",
  params: { screen: "home" },
});

이벤트 로깅 Tips

앱에서 수집하는 모든 이벤트를 로깅하면, Monetai가 비구매자 예측에 상관성이 높은 이벤트를 자동으로 선별하여 학습에 활용합니다.
수집중인 이벤트가 없는 경우 앱의 주요 기능이나 버튼, 특히 구매 이전에 발생하는 행동들에 이벤트를 심는 것을 권장합니다.

초기화 전 이벤트 처리

초기화가 완료되기 전에 발생한 이벤트는 큐(Queue)에 저장되었다가, 초기화가 완료된 후 자동으로 전송됩니다.

파라미터 사용 가이드라인

중요: 같은 이벤트 이름이라도 파라미터가 다르면 AI 모델이 별개의 이벤트로 인식합니다. 파라미터 값이 너무 다양하면 모델의 정확도가 떨어질 수 있습니다.

권장사항:

✅ 좋은 예: { screen: "home" }, { button: "upgrade" }, { category: "premium" }
❌ 피해야 할 예: { timestamp: "2024-01-15T10:30:00Z" }, { userId: "user123" }, { sessionId: "abc123" }

이유: 시간, 사용자 ID, 세션 ID와 같은 파라미터는 매번 고유한 이벤트를 생성하여 모델이 패턴을 찾기 어렵게 만듭니다. 구체적인 인스턴스보다는 사용자 행동 카테고리를 나타내는 파라미터에 집중하세요.

API Reference: MonetaiSDK.logEvent()

파라미터 (Parameters)

파라미터	타입	설명
eventName	string	이벤트 이름
params	object?	이벤트 파라미터 (선택사항)

다이나믹 프라이싱 구현

📌 필수 설정이 완료되었습니다. 이 섹션에서는 상품 노출을 기록하고 개인화된 오퍼를 조회하는 방법을 다룹니다.
핵심 워크플로우는: 각 화면에 placement를 정의하고 상품 조회를 기록 → getOffer()로 개인화 오퍼를 조회하는 것입니다.

1. 상품 조회 이벤트 기록

이 단계는 필수입니다. 사용자가 상품(가격 화면)을 조회할 때 MonetaiSDK.logViewProductItem()을 호출하여 노출을 기록합니다. 이 데이터는 Monetai의 오퍼 타게팅 최적화에 필수적이며, 기록하지 않으면 오퍼 개인화가 정상적으로 동작하지 않습니다.

상품별로 각각 로그해야 합니다

프로모션 화면에 여러 개의 상품이 표시되는 경우, 각 상품마다 logViewProductItem()을 개별적으로 호출해야 합니다. 사용자에게 노출된 모든 상품에 대해 각각 로그를 남겨 주세요.

모든 구매 화면

각 상품이 노출되는 화면에 설명적인 placement 값을 정의합니다 (예: main_paywall, special_offer, bottom_banner). 이 데이터는 Monetai가 가격을 최적화하는 데 사용됩니다. 추후 해당 화면에 프로모션을 생성할 때 동일한 placement 값을 프로모션의 placement로 설정하면, 기존에 수집된 데이터가 자동으로 연결됩니다. 이미 대시보드에서 프로모션을 생성했다면 대시보드 → 프로모션 → 프로모션 설정에서 placement 값을 확인할 수 있습니다.

import MonetaiSDK from "@hayanmind/monetai-react-native";

// 일반 구매 화면에서 기록
await MonetaiSDK.logViewProductItem({
  placement: "main_paywall",
  productId: "premium_monthly",
  price: 9.99,
  regularPrice: 9.99,
  currencyCode: "USD",
});

가격 최적화 화면

getOffer()를 사용하여 Monetai 가격 최적화가 적용된 화면에서는 (다음 섹션 참조) logViewProductItem()과 getOffer()에 동일한 placement 값을 사용합니다.

import MonetaiSDK from "@hayanmind/monetai-react-native";

// 사용자가 가격 화면을 볼 때 기록 — 상품별로 각각 호출
await MonetaiSDK.logViewProductItem({
  placement: "special_offer",
  productId: "premium_monthly",
  price: 4.99,
  regularPrice: 9.99,
  currencyCode: "USD",
});

await MonetaiSDK.logViewProductItem({
  placement: "special_offer",
  productId: "premium_yearly",
  price: 39.99,
  regularPrice: 79.99,
  currencyCode: "USD",
});

API Reference: MonetaiSDK.logViewProductItem()

매개변수 (ViewProductItemParams)

파라미터	타입	Required	설명
placement	string	✓	상품이 노출되는 화면 또는 UI 요소의 식별자 (예: `main_paywall`, `special_offer`, `bottom_banner`). 이미 대시보드에서 프로모션을 생성했다면 대시보드 → 프로모션 → 프로모션 설정에서 placement 값을 확인할 수 있습니다.
productId	string	✓	상품 ID (스토어 상품 ID)
price	number	✓	표시된 가격
regularPrice	number	✓	정가 (할인 전 가격)
currencyCode	string	✓	통화 코드 (예: `USD`, `KRW`)
month	number \| null	-	구독 기간 (개월 수)

2. 오퍼 조회하기

MonetaiSDK.getOffer(placement)를 호출하여 현재 사용자에게 적용 가능한 개인화된 오퍼를 조회합니다. 할인 대상인 경우 할인 정보와 상품 정보가 포함된 Offer 객체가 반환되며, 대상이 아닌 경우 null이 반환됩니다.

오퍼 활용 방법

오퍼가 반환된 경우: 최적화된 할인율과 상품 정보를 기존 가격/프로모션 화면에 적용합니다.
null이 반환된 경우: 다이나믹 프라이싱 최적화가 적용되지 않는 사용자 그룹입니다. 이 경우 앱에서 기존에 사용하던 기본 할인가를 그대로 적용하면 됩니다.

오퍼 중복 조회 주의

getOffer()는 호출할 때마다 AI 모델이 최적화한 결과를 반환하므로, 같은 사용자라도 호출 시점에 따라 다른 할인 결과가 반환될 수 있습니다. 프로모션이 활성화된 상태에서 getOffer()를 여러 번 호출하면, 사용자에게 표시되는 할인 상품이 의도치 않게 바뀔 수 있습니다.

발생 시나리오:

사용자가 가격 화면에 진입 → getOffer() 호출 → 30% 할인 표시
사용자가 화면을 나갔다가 다시 진입 → getOffer() 재호출 → 50% 할인 반환
같은 프로모션인데 다른 가격이 표시되어 사용자 혼란 발생

권장 사항: getOffer()는 한 번만 호출하고, 프로모션이 활성화되어 있는 동안 그 결과를 캐싱하여 사용하세요. 화면 진입 시마다 재호출하지 마세요.

하나의 오퍼에 여러 상품이 포함되는 경우

프로모션 페이지에 여러 상품(예: 1개월 플랜, 12개월 플랜)이 있고, 에이전트에 두 상품을 모두 등록한 경우 products에는 각 상품별로 개별 최적화된 결과가 포함됩니다. 예를 들어 1개월과 12개월 상품을 등록했다면, 두 상품 각각에 대해 최적화된 가격이 반환됩니다.

import MonetaiSDK from "@hayanmind/monetai-react-native";

const showPricingScreen = async () => {
  try {
    const offer = await MonetaiSDK.getOffer("YOUR_PLACEMENT");

    if (offer) {
      // 오퍼가 있는 경우 — 기존 UI에 할인 적용
      // products에는 등록된 상품별로 최적화된 결과가 포함됨
      console.log("에이전트:", offer.agentName);
      console.log("오퍼 상품:", offer.products);

      for (const product of offer.products) {
        console.log(`SKU: ${product.sku}, 할인율: ${product.discountRate * 100}%`);
      }

      displayPrice(offer);
    } else {
      // 오퍼 없음 — 기존 기본 할인가 표시
      displayDefaultPrice();
    }
  } catch (error) {
    console.error("오퍼 조회 실패:", error);
    displayDefaultPrice();
  }
};

API Reference: MonetaiSDK.getOffer()

매개변수 (Parameters)

파라미터	타입	설명
placement	string	가격 최적화를 적용할 화면의 고유 식별자. `logViewProductItem()`에서 정의한 값과 동일하게 사용합니다. 이미 대시보드에서 프로모션을 생성했다면 대시보드 → 프로모션 → 프로모션 설정에서 placement 값을 확인할 수 있습니다.

반환 값: Offer | null

Offer 타입

속성	타입	설명
agentId	number	에이전트 ID
agentName	string	에이전트 이름
products	OfferProduct[]	오퍼 상품 목록

OfferProduct 타입

속성	타입	설명
name	string	상품 이름
sku	string	상품 SKU (스토어 상품 ID)
discountRate	number	할인율 (0-1 범위, 예: 0.5 = 50%)

사용자 상태 관리

SDK Reset

사용자가 로그아웃 할 때 SDK를 초기화 합니다.

import MonetaiSDK from "@hayanmind/monetai-react-native";

// 사용자 로그아웃 시
const logoutUser = async () => {
  try {
    await MonetaiSDK.reset();
    console.log("사용자 로그아웃 완료");
  } catch (error) {
    console.error("사용자 로그아웃 실패:", error);
  }
};

Support
SDK 연동 중 문제가 발생하면 support@monetai.io로 편하게 문의해 주세요.

다음 단계

SDK 설정이 완료되면 다음 단계를 진행하세요:

프로모션 시작하기

사전 요구사항​

SDK 설정​

1. SDK 설치​

2. SDK 초기화​

3. 사용자 이벤트 기록​

다이나믹 프라이싱 구현​

1. 상품 조회 이벤트 기록​

모든 구매 화면​

가격 최적화 화면​

2. 오퍼 조회하기​

사용자 상태 관리​

SDK Reset​

다음 단계​