본문으로 건너뛰기
📌 8월 넷째주 릴리즈 노트: 프로모션 UI 템플릿 출시! 간단하게 페이월을 만들고 캠페인을 즉시 시작할 수 있어요. 자세히 보기
버전: Legacy

Android SDK

Monetai Android SDK는 앱 내에서 구매자를 예측하여 프로모션을 효과적으로 구현할 수 있도록 돕습니다. 이 가이드는 SDK 설치부터 초기화, 주요 기능 사용법까지 전 과정을 안내합니다.

사전 요구사항​

  • Android API Level 21 (Android 5.0) 이상
  • Google Play Billing Library v8 (SDK 버전 2.0.0 이상)
  • Google Play Billing Library v7 (SDK 버전 1.x)

📚 추가 리소스​

🔧 언어 지원​

Monetai Android SDK는 Kotlin과 Java 모두를 지원합니다. 프로젝트 언어에 따라 아래 적절한 탭을 선택하세요.

필수 SDK 연동​

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

1. SDK 설치​

Gradle을 사용하여 프로젝트에 Monetai Android SDK를 추가하세요.

// Add JitPack repository
repositories {
    maven { url 'https://jitpack.io' }
}

// Add dependency
dependencies {
    implementation 'com.github.hayanmind:monetai-android:2.0.0'
}
Billing Library 버전 호환성

SDK 버전 2.0.0 이상:

  • 내부적으로 Google Play Billing Library v8 포함
  • Google Play Billing Library v8 이상 필요

SDK 버전 1.x:

  • 내부적으로 Google Play Billing Library v7 포함
  • Google Play Billing Library v7과 호환

v1.x에서 v2.0.0으로 마이그레이션:

  • 앱 코드 변경 불필요
  • Gradle이 자동으로 의존성 해결
  • 중요: 다른 결제 라이브러리 사용 시 Billing Library v8 호환성 확인 필요

2. SDK 초기화​

앱이 시작될 때 SDK를 초기화합니다.

import com.monetai.sdk.MonetaiSDK

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Monetai SDK 초기화
        MonetaiSDK.shared.initialize(
            context = this@MainActivity,
            sdkKey = "YOUR_SDK_KEY", // Monetai 대시보드에서 발급받은 SDK 키
            userId = "USER_ID" // 앱 사용자의 사용자 ID
        ) { result, error ->
            if (error != null) {
                println("Monetai SDK 초기화 실패: ${error.message}")
            } else {
                println("Monetai SDK 초기화 완료: $result")
            }
        }
    }
}

API 참조

매개변수

매개변수타입설명
contextContext애플리케이션 컨텍스트
sdkKeystringMonetai에서 발급받은 SDK 키 (설정 > SDK 통합)
userIdstring앱 사용자의 사용자 ID (없을 경우 이메일, 디바이스 ID 등 고유 식별값 활용)
completioncallback?초기화 완료 시 호출되는 콜백 (선택사항)

콜백 매개변수

매개변수타입설명
resultInitializeResult?초기화 성공 시 결과
errorException?초기화 실패 시 오류

InitializeResult 타입

반환값타입설명
organizationIdnumber조직 ID
platform'android'플랫폼 정보
versionstringSDK 버전
userIdstring설정된 사용자 ID
groupABTestGroup | nullA/B 테스트 그룹

ABTestGroup 타입

값설명
monetai자동 프로모션이 있는 실험 그룹
baseline프로모션이 없는 대조 그룹
unknown캠페인에 포함되지 않은 사용자
null현재 캠페인이 없을 때


3. 사용자 이벤트 기록​

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

import com.monetai.sdk.MonetaiSDK

// 기본 이벤트 로깅
MonetaiSDK.shared.logEvent("app_in")

// 매개변수가 있는 이벤트 로깅
MonetaiSDK.shared.logEvent(
    eventName = "screen_in",
    params = mapOf("screen" to "home")
)

API 참조

매개변수

매개변수타입설명
eventNamestring이벤트 이름
paramsMap<String, Any>?이벤트 매개변수 (선택사항)
이벤트 로깅 Tips
  • 앱에서 수집하는 모든 이벤트를 로깅하면, Monetai가 비구매자 예측에 상관성이 높은 이벤트를 자동으로 선별하여 학습에 활용합니다.
  • 수집중인 이벤트가 없는 경우 앱의 주요 기능이나 버튼, 특히 구매 이전에 발생하는 행동들에 이벤트를 심는 것을 권장합니다.
초기화 전 이벤트 처리

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

파라미터 사용 가이드라인

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

권장사항:

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

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



프로모션 기능 구현​

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

1. 구매 예측하기​

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

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

fun predictUserPurchase() {
    MonetaiSDK.shared.predict { result, error ->
        if (error != null) {
            println("예측 실패: ${error.message}")
            return@predict
        }

        println("예측 결과: ${result?.prediction}")
        println("테스트 그룹: ${result?.testGroup}")

        when (result?.prediction) {
            PredictResult.NON_PURCHASER -> {
                // 미구매자로 예측된 경우 할인 제공
                println("미구매자로 예측됨 - 할인 적용 가능")
            }
            PredictResult.PURCHASER -> {
                // 구매자로 예측된 경우
                println("구매자로 예측됨 - 할인 불필요")
            }
            null -> {
                // 예측 불가
                println("예측 불가 - 활성 캠페인 또는 모델 없음")
            }
        }
    }
}

API 참조

반환값

반환값타입설명
predictionPredictResult예측 결과
testGroupABTestGroupA/B 테스트 그룹

PredictResult 타입

값설명
NON_PURCHASER구매하지 않을 것으로 예측
PURCHASER구매할 것으로 예측
null예측 불가 (모델 생성 전 또는 활성 캠페인 없음)
predict() 함수 중요 참고사항
  1. 여러 번 호출하는 경우
    • 이전에 predict()를 호출해서 프로모션이 활성화된 상태에서는 predict()를 여러 번 호출해도 새로운 프로모션이 시작되지 않습니다. onDiscountInfoChange 콜백으로 동일한 프로모션 정보만 반환됩니다.
  2. 프로모션 다시 시작
    • 프로모션 기간이 종료된 후에 predict()를 다시 호출하면, 사용자가 여전히 미구매자로 예측되는 경우 새로운 프로모션이 시작됩니다.
  3. 유료 구독 사용자 제외 - 이미 유료 구독 중인 사용자에게는 프로모션을 제공하지 않으려면, 해당 사용자에 대해서는 predict() 함수를 호출하지 않도록 처리해야 합니다.

2. 프로모션 UI 노출하기​

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

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

MonetaiSDK.shared.configurePaywall()에 paywallConfig를 전달하세요. predict()가 비구매자를 반환하고 할인이 유효 기간 내에 있을 때, 배너/페이월이 자동으로 나타납니다.

Paywall UI 템플릿 지원

Paywall UI 템플릿은 Android SDK 1.1.0 이상에서 지원됩니다.

UI 템플릿 살펴보기

사용 가능한 템플릿 스타일과 예제를 확인하세요: UI 템플릿 디자인 가이드

import com.monetai.sdk.MonetaiSDK
import com.monetai.sdk.models.PaywallConfig
import com.monetai.sdk.models.Feature
import com.monetai.sdk.models.PaywallStyle

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // 페이월 구성
        configurePaywall()

        // 구독 상태 설정 (사용자의 실제 구독 상태에 따라 초기값 설정)
        MonetaiSDK.shared.setSubscriptionStatus(false)
    }

    private fun configurePaywall() {
        val features = listOf(
            Feature("모든 프리미엄 기능", "모든 기능 잠금 해제", true),
            Feature("고급 분석", "인사이트 및 상세 리포트"),
            Feature("우선 지원", "24/7 고객 지원")
        )

        val config = PaywallConfig(
            discountPercent = 50,
            regularPrice = "₩10,000",
            discountedPrice = "₩5,000",
            locale = "ko",
            style = PaywallStyle.HIGHLIGHT_BENEFITS,
            features = features,
            enabled = true,
            bannerBottom = 20f
        ).apply {
            onPurchase = { paywallContext, closePaywall ->
                // TODO: 구매 플로우 실행
                // 성공 시 페이월 닫기 및 구독자 상태 업데이트
                closePaywall()
                MonetaiSDK.shared.setSubscriptionStatus(true)
            }

            onTermsOfService = { paywallContext ->
                // TODO: 이용약관 열기
            }

            onPrivacyPolicy = { paywallContext ->
                // TODO: 개인정보처리방침 열기
            }
        }

        MonetaiSDK.shared.configurePaywall(config)
    }
}

PaywallConfig

키타입필수설명
discountPercentInt✓할인 비율 (0-100)
regularPriceString✓정가 라벨
discountedPriceString✓할인가 라벨
localeString✓언어 코드 (예: "ko", "en")
stylePaywallStyle✓템플릿 스타일
featuresList<Feature>-.HIGHLIGHT_BENEFITS 또는 .KEY_FEATURE_SUMMARY에만 필요
enabledBoolean-자동 배너/페이월 표시 활성화 (기본값: true)
bannerBottomFloat-플로팅 배너의 하단 오프셋 (기본값: 20f)

PaywallStyle 타입

값설명
.COMPACT컴팩트 디자인
.HIGHLIGHT_BENEFITS혜택 강조 디자인
.KEY_FEATURE_SUMMARY핵심 기능 요약 디자인
.TEXT_FOCUSED텍스트 중심 디자인

Feature 모델

속성타입설명
titleString기능 제목
descriptionString기능 설명
isPremiumOnlyBoolean프리미엄 전용 기능 여부 (기본값: false)

콜백

콜백타입설명
onPurchase(PaywallContext, (() -> Unit) -> Unit)?구매 버튼 콜백 (성공 시 closePaywall() 호출)
onTermsOfService(PaywallContext -> Unit)?이용약관 클릭 콜백
onPrivacyPolicy(PaywallContext -> Unit)?개인정보처리방침 클릭 콜백

PaywallContext

PaywallContext는 UI 작업을 위한 현재 액티비티 및 애플리케이션 컨텍스트에 대한 액세스를 제공합니다:

속성타입설명
activityActivityUI 작업을 위한 현재 액티비티
applicationContextContext리소스를 위한 애플리케이션 컨텍스트

구독 상태 관리

SDK는 사용자의 구독 상태에 따라 배너/페이월 표시를 자동으로 제어합니다. 다음 메서드를 사용하여 구독 상태를 관리하세요:

// 초기 구독 상태 설정 (configurePaywall 전후 모두 가능)
MonetaiSDK.shared.setSubscriptionStatus(true) // 구독자는 true, 비구독자는 false

자동 배너 제어

페이월이 구성되면 SDK가 자동으로:

  • 할인이 활성화되고, 페이월이 활성화되고, 사용자가 구독자가 아닐 때 배너 표시
  • 사용자가 구독자이거나, 할인이 없거나, 할인이 만료되었거나, 페이월이 비활성화되었을 때 배너 숨김

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

B-1. onDiscountInfoChange 콜백을 사용한 구현

프로모션 화면 구현

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

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

  • 유효 기간 동안에만 프로모션 화면 노출하기
  • 기간이 만료되면 프로모션 화면 숨기기
콜백 등록 타이밍

중요: onDiscountInfoChange 콜백은 initialize() 호출 전에 등록해야 합니다.

나중에 콜백을 등록하면 기존 활성 프로모션 정보를 놓칠 수 있습니다. 이는 앱이 재시작될 때 이전에 활성화된 프로모션을 즉시 표시할 수 없는 문제를 일으킬 수 있습니다.

실시간 UI 업데이트

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

import com.monetai.sdk.MonetaiSDK
import com.monetai.sdk.models.AppUserDiscount
import java.util.Date

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // initialize() 호출 전에 할인 정보 변경 콜백 설정
        MonetaiSDK.shared.onDiscountInfoChange = { discountInfo ->
            runOnUiThread {
                handleDiscountInfoChange(discountInfo)
            }
        }

        // 콜백 설정 후 SDK 초기화
        MonetaiSDK.shared.initialize(
            context = this@MainActivity,
            sdkKey = "YOUR_SDK_KEY",
            userId = "USER_ID"
        ) { result, error ->
            // 초기화 결과 처리
        }
    }

    private fun handleDiscountInfoChange(discountInfo: AppUserDiscount?) {
        if (discountInfo != null) {
            // 할인 정보가 사용 가능할 때 UI 업데이트
            val now = Date()
            val endTime = discountInfo.endedAt

            if (now < endTime) {
                // 할인이 유효할 때
                showDiscountBanner(discountInfo)
            }
        } else {
            // 할인 정보가 없을 때
            hideDiscountBanner()
        }
    }

    private fun showDiscountBanner(discount: AppUserDiscount) {
        // 할인 배너 표시 로직
        println("할인 배너 표시: $discount")
    }

    private fun hideDiscountBanner() {
        // 할인 배너 숨김 로직
        println("할인 배너 숨김")
    }
}

API 참조

콜백 타입

public var onDiscountInfoChange: ((AppUserDiscount?) -> Unit)?

AppUserDiscount 타입

속성타입설명
idnumber할인 ID
startedAtDate할인 시작 시간
endedAtDate할인 종료 시간
appUserIdstring사용자 ID
sdkKeystringSDK 키
createdAtDate생성 시간

사용자 상태 관리​

SDK 재설정​

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

import com.monetai.sdk.MonetaiSDK

// 사용자 로그아웃 시
fun logoutUser() {
    MonetaiSDK.shared.reset()
    println("사용자 로그아웃 완료")
}

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

다음 단계​

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