버전: Legacy

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
group	ABTestGroup \| null	A/B 테스트 그룹

ABTestGroup 타입

값	설명
monetai	프로모션이 자동 적용되는 실험군
baseline	프로모션이 적용되지 않는 대조군
unknown	캠페인에 포함되지 않은 유저
null	현재 캠페인이 존재하지 않는 경우

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?	이벤트 파라미터 (선택사항)

프로모션 기능 구현

📌 필수 연동이 완료되었다면, 이제 프로모션 로직을 구현할 차례입니다.
구매 예측을 요청하고 그 결과를 활용하여 사용자에게 맞춤 프로모션 UI를 보여주는 방법을 확인해 보세요.

1. 구매 예측하기

사용자가 상품을 구매할지 예측하려면, 앱 내 핵심적인 구매 결정 순간에 predict() 함수를 호출하세요.

[권장] predict 함수는 1개의 시점에만 호출하세요!

사용자 경험을 최적화하고 캠페인 성과를 가장 명확하게 측정하기 위해, predict() 함수는 1개의 시점에만 호출하는 것을 권장합니다.
사용자가 상품의 가치를 충분히 인지하고, 구매를 가장 망설이는 순간에 호출하는 것이 가장 효과적입니다.
앱의 특성에 따라 아래와 같은 시점을 고려해볼 수 있습니다.
- 정상가 구독 페이지를 이탈했을 때
- 메인 플로우를 완료했을 때
- 프리미엄 기능을 사용하려고 시도했을 때

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

const predictUserPurchase = async () => {
  try {
    const result = await MonetaiSDK.predict();

    console.log("예측 결과:", result.prediction);
    console.log("테스트 그룹:", result.testGroup);

    if (result.prediction === "non-purchaser") {
      // 미구매자로 예측된 경우 할인 제공
      console.log("미구매자로 예측됨 - 할인 적용 가능");
    } else if (result.prediction === "purchaser") {
      // 구매자로 예측된 경우
      console.log("구매자로 예측됨 - 할인 불필요");
    }
  } catch (error) {
    console.error("예측 실패:", error);
  }
};

API Reference: MonetaiSDK.predict()

반환 값 (Return Value)

반환값	타입	설명
prediction	PredictResult	예측 결과
testGroup	ABTestGroup	A/B 테스트 그룹

PredictResult 타입

값	설명
non-purchaser	구매하지 않을 것으로 예측
purchaser	구매할 것으로 예측
null	예측 불가 (모델 생성 전이나 시작된 캠페인 없을 때)

predict() 함수 중요 참고사항

여러 번 호출하는 경우
- 이전에 predict()를 호출해서 프로모션이 활성화된 상태에서는 predict()를 여러 번 호출해도 새로운 프로모션이 시작되지 않습니다. onDiscountInfoChange 콜백으로 동일한 프로모션 정보만 반환됩니다.
프로모션 다시 시작
- 프로모션 기간이 종료된 후에 predict()를 다시 호출하면, 사용자가 여전히 미구매자로 예측되는 경우 새로운 프로모션이 시작됩니다.
유료 구독 사용자 제외 - 이미 유료 구독 중인 사용자에게는 프로모션을 제공하지 않으려면, 해당 사용자에 대해서는 predict() 함수를 호출하지 않도록 처리해야 합니다.

2. 프로모션 UI 노출하기

predict() 호출 결과 사용자가 미구매자로 예측되면, SDK는 MonetaiProvider를 통해 할인 정보를 전달합니다. 이 정보로 사용자에게 프로모션 UI를 보여줄 수 있습니다.

A. UI 템플릿 사용하기 (권장)

MonetaiProvider에 paywallConfig를 전달하고 predict() 호출 결과가 미구매자로 예측되면, 할인 유효기간 동안 배너/페이월이 자동으로 표시됩니다.

제공 범위

Paywall UI 템플릿은 React Native SDK 0.4.0 이상에서 지원됩니다.

UI 템플릿 자세히 보기

제공되는 템플릿 스타일과 상세 예시는 다음 문서에서 확인할 수 있습니다: UI 템플릿 디자인 가이드

import React, { useState } from "react";
import MonetaiSDK, { MonetaiProvider } from "@hayanmind/monetai-react-native";
import { Button, View } from "react-native";

export default function App() {
  const [isSubscriber, setIsSubscriber] = useState(/* 고객의 실제 구독 상태 */);

  const runPredict = async () => {
    const result = await MonetaiSDK.predict();
    console.log("Predict result:", result);
  };

  return (
    <MonetaiProvider
      paywallConfig={{
        enabled: true,
        isSubscriber, // 구독자는 배너/페이월 숨김
        locale: "ko",
        style: "highlight-benefits", // 'compact' | 'highlight-benefits' | 'key-feature-summary' | 'text-focused'

        // 결제/가격 표시 (고객사 정책에 맞게 설정)
        discountPercent: 50,
        regularPrice: "₩10,000",
        discountedPrice: "₩5,000",
        // features는 style이 'highlight-benefits' 또는 'key-feature-summary'일 때만 필요합니다
        features: [
          {
            title: "프리미엄 전체 기능",
            description: "모든 프리미엄 기능 이용",
            isPremiumOnly: true,
          },
          {
            title: "심층 분석 리포트",
            description: "세부 인사이트와 리포트 제공",
          },
          { title: "우선 지원", description: "24/7 고객 지원" },
        ],

        // 선택: 배너/페이월 위치·표시 우선순위
        // 배너 위치 오프셋(하단 기준, px)
        bannerBottom: 20,
        // iOS: 다른 컴포넌트에 가려질 때 z-order 조정
        bannerZIndex: 1000,
        paywallZIndex: 2000,
        // Android: 다른 컴포넌트에 가려질 때 z-order 조정
        bannerElevation: 8,
        paywallElevation: 16,

        // 콜백들
        onPurchase: async (closePaywall) => {
          // TODO: 앱의 결제 플로우 실행
          // 성공 시 페이월 닫고 구독자 상태 갱신
          closePaywall();
          setIsSubscriber(true);
        },
        onTermsOfService: () => {
          // TODO: 이용약관 화면 열기
        },
        onPrivacyPolicy: () => {
          // TODO: 개인정보처리방침 화면 열기
        },
      }}
    >
      <View>
        <Button title="예측 실행" onPress={runPredict} />
      </View>
    </MonetaiProvider>
  );
}

PaywallConfig

Key	Type	Required	설명
enabled	boolean	✓	배너/페이월 자동 표시 활성화
isSubscriber	boolean	✓	구독자 여부 (true면 표시 안 함)
locale	string	✓	언어 코드 (예: `ko`, `en`)
discountPercent	number	✓	할인율 (0-100)
style	`'compact' \| 'highlight-benefits' \| 'key-feature-summary' \| 'text-focused'`	✓	템플릿 스타일
regularPrice	string	✓	정가 표시 문자열
discountedPrice	string	✓	할인 가격 표시 문자열
features	`Array<{ title: string; description: string; isPremiumOnly?: boolean }>`	-	스타일이 `'highlight-benefits'` 또는 `'key-feature-summary'`일 때만 필요
bannerBottom	number	-	배너 하단 오프셋
bannerZIndex	number	-	배너 z-index
bannerElevation	number	-	배너 elevation (Android)
paywallZIndex	number	-	페이월 z-index
paywallElevation	number	-	페이월 elevation (Android)
onPurchase	`(closePaywall: () => void) => void`	-	구매 버튼 콜백 (성공 시 `closePaywall()` 호출)
onTermsOfService	`() => void`	-	이용약관 클릭 콜백
onPrivacyPolicy	`() => void`	-	개인정보처리방침 클릭 콜백

B. UI 직접 구현하기 (고급)

프로모션 화면 구현

프로모션 화면을 직접 구현할 수 있습니다. Monetai SDK가 제공하는 할인 적용 시점(startedAt, endedAt) 정보와 onDiscountInfoChange 콜백을 활용, 실제 UI 컴포넌트와 프로모션 화면 로직을 직접 구현하여 사용할 수 있습니다.

할인 정보에 포함된 startedAt과 endedAt 값은 프로모션의 유효 기간을 나타냅니다. 이 타임스탬프를 사용하여 아래와 같이 처리해야 합니다.

유효 기간 동안에만 프로모션 화면 노출하기
기간이 만료되면 프로모션 화면 숨기기

import MonetaiSDK, { MonetaiProvider } from "@hayanmind/monetai-react-native";

const App = () => {
  const [discountInfo, setDiscountInfo] = useState(null);

  const handleDiscountInfoChange = (newDiscountInfo) => {
    setDiscountInfo(newDiscountInfo);

    if (newDiscountInfo) {
      // 할인 정보가 있을 때 UI 업데이트
      const now = new Date();
      const endTime = new Date(newDiscountInfo.endedAt);

      if (now < endTime) {
        // 할인이 유효한 경우
        showDiscountBanner(newDiscountInfo);
      }
    } else {
      // 할인 정보가 없을 때
      hideDiscountBanner();
    }
  };

  const showDiscountBanner = (info) => {
    // 할인 배너 표시 로직
    console.log("할인 배너 표시:", info);
  };

  const hideDiscountBanner = () => {
    // 할인 배너 숨김 로직
    console.log("할인 배너 숨김");
  };

  return (
    <MonetaiProvider onDiscountInfoChange={handleDiscountInfoChange}>
      {/* 앱 컴포넌트들 */}
      {discountInfo && <DiscountBanner discountInfo={discountInfo} />}
    </MonetaiProvider>
  );
};

실시간 UI 업데이트

onDiscountInfoChange 콜백은 앱 시작 시 유효한 할인 정보가 있거나, predict() 함수 호출 후 새로운 할인 정보가 생성될 때 모두 호출됩니다. 이 콜백을 활용하여 배너, 가격 정보 등 UI를 실시간으로 업데이트할 수 있습니다.

API Reference: MonetaiProvider

속성 (Props)

Props	타입	설명
children	ReactNode	자식 컴포넌트들
onDiscountInfoChange	(discountInfo: DiscountInfo \| null) => void	할인 정보 변경 콜백

DiscountInfo 타입

속성	타입	설명
startedAt	Date	할인 시작 시간
endedAt	Date	할인 종료 시간
userId	string	사용자 ID
sdkKey	string	SDK 키

사용자 상태 관리

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. 프로모션 UI 노출하기​

A. UI 템플릿 사용하기 (권장)​

B. UI 직접 구현하기 (고급)​

사용자 상태 관리​

SDK Reset​

다음 단계​