서드파티 마켓

이해하기

구글 플레이·애플 앱스토어 외의 모바일 마켓(원스토어)에서 게임을 서비스하기 위한 결제 연동 기능이에요.
각 마켓의 결제 시스템을 STOVE SDK의 IAP 인터페이스로 통일하여 처리할 수 있도록 지원해요.

기본 결제 흐름은 구글(IAP) 연동과 동일하며, 각 마켓별 전용 IAP 모듈(iap-onestore)을 선언하고 파트너스 설정을 추가하는 방식으로 적용해요.
이외의 SDK 기능(인증·로그·푸시 등)은 표준 Android 모듈을 그대로 적용하면 돼요.

적용 환경 및 동작 범위

연동 흐름

서드파티 마켓 연동은 파트너스 설정 → 모듈 적용 → SDK 구현 3단계로 진행돼요.

파트너스에서 마켓별 정보를 등록해요.

• 모바일 마켓 정보: Package Name, 빌링 키, App ID 등
• 마켓별 IAP 정보: 빌링 연동용 ID, 마켓 인증 정보
• 상품 ID 매핑: 마켓 상품 관리 메뉴에서 원스토어 상품 ID 등록

게임 프로젝트의 build.gradle에 스토브 저장소와 사용할 마켓의 IAP 모듈을 추가해요.
원스토어를 사용하는 경우 ONE Store SDK 저장소를 함께 등록해요.

구글(IAP) 연동과 동일한 흐름이에요. 마켓별 차이는 모듈이 내부적으로 처리하므로 별도 분기 코드를 작성할 필요는 없어요.

1. initialize() 호출 — SDK 초기화
2. setListener() 등록 — 결제 이벤트 수신 리스너 설정
3. 결제 결과 처리 — 성공·실패·취소 분기 구현

연동 가이드

연동 준비

서드파티 마켓 연동 전에 마켓별 개발자 콘솔에 게임을 등록하고 필요한 인증 정보를 발급받아야 해요.

원스토어 설정

원스토어 연동은 파트너스의 3개 메뉴에서 진행해요.
원스토어는 OAuth 인증 정보(Client ID·Secret·License Key)를 추가로 등록해요.

파트너스 모바일 마켓 정보 메뉴에서 마켓 종류를 원스토어로 선택하고 다음 항목을 등록해요.

파트너스 마켓 별 IAP 정보 관리 메뉴에서 마켓 항목을 ONE store로 선택하고, 다음 4개 항목을 모두 입력해요.

파트너스 마켓 상품 관리 메뉴에서 상품 정보를 입력하고,
마켓 상품 ID(원스토어) 컬럼에 원스토어에 등록한 상품 ID를 매핑해요.

개발하기

원스토어 구현

원스토어 결제는 iap-onestore 모듈을 적용한 뒤 initialize → setListener 순으로 호출해요. 결제 결과는 setListener 콜백으로 전달되며, 일부 에러 코드(RESULT_NEED_UPDATE / RESULT_NEED_LOGIN)는 SDK가 다국어 메시지를 자동으로 제공해요.

사전 준비

• 파트너스 설정(모바일 마켓 정보·마켓 별 IAP 정보·마켓 상품 ID 매핑)은 2. 연동 가이드 섹션에서 완료된 상태여야 해요.
• 원스토어 콘솔에서 발급한 OAuth Client ID / Client Secret / License Key가 파트너스에 등록돼 있어야 해요.
• 모듈은 Android 빌드에만 적용해요. (iOS는 적용 대상 아님)

모듈 적용 (build.gradle)

build.gradle에 스토브 저장소와 ONE Store SDK 저장소 두 개를 함께 등록하고, iap-onestore 모듈 의존성을 추가해요. 최신 버전은 SDK 다운로드 및 설치에서 확인하세요.

repositories {
    google()
    jcenter()

    maven {
        url "https://externalnexus.iam0.com/repository/mvp" // for Stove
        // Android Gradle Plugin 7.0 이상 사용 시 옵션 추가
        allowInsecureProtocol = true
    }

    mavenCentral() // for Facebook

    maven {
        url "https://repo.onestore.net/repository/onestore-sdk-public" // for OneStore
        allowInsecureProtocol = true
    }
}

dependencies {
    // 릴리즈노트 기준 최신 버전으로 적용하세요.
    implementation 'com.stove:iap-onestore:2.8.0'
}

개발 흐름

1. OneStore 객체 생성: Activity 컨텍스트로 OneStore(activity) 인스턴스를 만들어요.
2. initialize() 호출: 초기화 콜백에서 결과를 분기 처리해요.
   • 성공 → setListener() 호출
   • Auth.UnauthorizedError(30002) → 로그인 화면으로 유도
   • 그 외 실패(InitializeError) → IAP.ResponseCodeKey / IAP.DebugMessageKey 추출 후 이용자 안내
3. setListener() 등록: 결제 결과를 받을 리스너를 등록해요. 게임이 활성 상태인 동안 1회 등록하면 돼요.
4. 결제 결과 분기 처리: 콜백으로 들어온 result.errorCode를 분기해 각 케이스를 처리해요. (아래 표 참고)

결제 결과 분기

참고: flush() 동작

원스토어는 비동기식 미지급결제 조회 함수를 제공하기 때문에 flush()의 반환값은 **항상 true**예요. 미지급건 처리는 기존 IAP와 동일하게 동작하므로, flush()의 리턴값을 분기 조건으로 직접 참조하지 않는다면 게임 구현에 영향이 없어요.

샘플 코드

private val iap: OneStore by lazy {
    OneStore(activity)
}

private fun initialize() {
    iap.initialize { result ->
        when {
            result.isSuccessful() -> {
                setListener() // setListener 호출
            }
            result.errorCode == Auth.UnauthorizedError -> {
                // TODO: login
            }
            else -> {
                // InitializeError
                val responseCode = result.userInfo!!.getValue(IAP.ResponseCodeKey)
                // RESULT_NEED_LOGIN / RESULT_NEED_UPDATE는 다국어 메시지 적용됨
                val debugMessage = result.userInfo!!.getValue(IAP.DebugMessageKey)
            }
        }
    }
}

private fun setListener() {
    iap.setListener { result, product, purchaseDetail ->
        when {
            result.isSuccessful() -> {
                // 구매 성공
            }
            result.isCanceled() -> {
                // 구매 취소 → 화면 다시 표시
            }
            result.isServerError() -> {
                // 빌링 서버 오류
            }
            result.errorCode == SuccessButUserMissMatch -> {
                // 결제 검증 시점과 현재 계정 불일치 — deliveryMethod 정책에 따라 처리
            }
            result.errorCode == Purchased -> {
                // 결제 검증 대기 — 푸시 활성화 안내
            }
            result.errorCode == Waiting -> {
                // 지급 대기 — 푸시 활성화 안내
            }
            result.errorCode == MarketError -> {
                val responseCode = result.userInfo!!.getValue(IAP.ResponseCodeKey)
                val debugMessage = result.userInfo!!.getValue(IAP.DebugMessageKey)
            }
        }
    }
}

자주 묻는 질문