대한민국 외 국가 및 지역 배포를 위한 가이드

원스토어 서비스 구성

개발자는 원스토어 개발자센터에 한 번의 상품 등록으로 대한민국과 그 외 국가 및 지역에 상품을 판매할 수 있습니다.
- 기존 한국 원스토어에 상품을 등록하여 판매하고 있던 개발자는 그 외 국가 및 지역에 배포를 선택하기만 하면 됩니다.
- 원스토어 개발자센터는 개발자가 등록한 앱을 Re-Packaging하여 대한민국 외 국가/지역 서비스용 APK를 생성하고, 이를 원스토어 사용자에게 배포합니다.
원스토어 클라이언트와 서버는 대한민국과 대한민국 외 지역/국가가 별도로 구성되어 있습니다.
- App에서 IAP SDK API를 호출하면 서비스 국가/지역에 맞는 원스토어 클라이언트/서버와 자동으로 연동됩니다.
- 개발사 서버에서 IAP Server API를 호출하는 경우, 마켓 구분코드(x-market-code)를 전달해야 합니다.

원스토어 설치자 정보 및 마켓 코드

SDK

SDK 버전

대한민국 외 국가 및 지역에 배포를 위해서는 원스토어 인앱결제 SDK V19 (API V6) 이상이 적용되어야 합니다.
SDK V17을 이용 중인 경우 SDK를 업그레이드 하셔야 합니다.
SDK V16을 이용 중인 경우 SDK V21 이상이 적용된 앱을 새로 등록 하셔야 합니다.

앱 무결성을 체크하는 보안 솔루션이 적용된 앱의 경우 보안 솔루션과의 충돌 이슈가 수정된 SDK 적용이 필요합니다. 두 버전 모두 충돌 이슈가 해결 되었으나 최신의 SDK 를 적용하는 것을 권장합니다.

SDK V21.02 가이드

원스토어 클라이언트 연동

대한민국 원스토어와 그 외 국가/지역의 원스토어는 별도의 앱으로 서비스 됩니다.
기존에 원스토어에서 서비스 되고 있는 V19 이상의 앱은 대한민국 외 국가/지역으로 바로 배포 할 수 있습니다.

SDK를 통한 마켓 구분 코드 획득

사용자가 다운로드 받은 마켓 플레이스 정보(대한민국 또는 그외 국가/지역)를 알고 싶을 경우에는 마켓 구분 코드를 획득해야 합니다.
획득한 마켓 구분 코드는 서버 API를 이용할 때 이용 중인 스토어를 확인하여 헤더로 전송해야 합니다.
마켓 구분 코드 획득 방법
- v19 : https://onestore-dev.gitbook.io/dev/tools/tools/old-version/v19/undefined-3/classes/purchaseclient#purchaseclient-getstoreinfoasync
- v21 : https://onestore-dev.gitbook.io/dev/tools/tools/v21/references/c-classes/c-purchaseclient#id-c-purchaseclient-getstoreinfoasync

스토어 지정을 위한 개발자 옵션 설정

IAP SDK 21.02.00 부터 아래와 같이 onestore:dev_option의 android:value 값을 설정하면, SDK와 연동되는 스토어 앱을 지정 할 수 있습니다.

<manifest>
    <application>
        <meta-data android:name="onestore:dev_option" android:value="onestore_01" />
    </application>
</manifest>

값 (android:value)

대상 국가 및 지역

onestore_00

대한민국 (South Korea) (기본값)

onestore_01

싱가포르, 타이완 (Singapore, Taiwan)

onestore_02

미국 – Digital Turbine (United States)

21.01.00 버전에서는 android:value 값이 global만 설정 가능하며, 싱가포르/타이완 스토어 앱만 지정이 가능했습니다.

주의: 배포 버전의 바이너리에서는 이 옵션을 반드시 제거해주세요.

StoreEnvironment API 기능 추가

StoreEnvironment.getStoreType() API는 SDK가 탑재된 애플리케이션이 원스토어를 통해 설치되었는지를 판단하는 기능을 제공합니다.

Store Type 정의

해당 API는 StoreType을 반환하며, 아래 네 가지 값 중 하나를 가집니다.

StoreType

value

description

StoreType.UNKNOWN

앱 설치 스토어 정보를 알 수 없음 (APK 직접 설치, 출처 불명 등)

StoreType.ONESTORE

ONE Store에서 설치됨 (또는 개발자 옵션이 활성화된 경우)

StoreType.VENDING

Google Play Store에서 설치됨

StoreType.ETC

기타 스토어에서 설치됨

API 사용 방법

해당 API는 StoreEnvironment.getStoreType()을 호출하여 사용할 수 있습니다.

import com.gaa.sdk.base.StoreEnvironment

val storeType = StoreEnvironment.getStoreType()

when (storeType) {
    StoreType.ONESTORE -> println("ONE Store에서 설치된 앱입니다.")
    StoreType.VENDING -> println("Google Play Store에서 설치된 앱입니다.")
    StoreType.ETC -> println("기타 스토어에서 설치된 앱입니다.")
    StoreType.UNKNOWN -> println("스토어 정보를 알 수 없습니다.")
}

import com.gaa.sdk.base.StoreEnvironment;

int storeType = StoreEnvironment.getStoreType();

switch (storeType) {
    case StoreType.ONESTORE:
        System.out.println("ONE Store에서 설치된 앱입니다.");
        break;
    case StoreType.VENDING:
        System.out.println("Google Play Store에서 설치된 앱입니다.");
        break;
    case StoreType.ETC:
        System.out.println("기타 스토어에서 설치된 앱입니다.");
        break;
    case StoreType.UNKNOWN:
    default:
        System.out.println("스토어 정보를 알 수 없습니다.");
        break;
}

스토어 판단 기준

이 API는 세 가지 방법을 통해 설치된 스토어를 판별합니다.

원스토어 마켓 서명을 통해 배포된 경우
1. 원스토어의 마켓 서명을 통한 배포 여부를 확인하여, 원스토어에서 설치된 앱인지 확인합니다.
Installer Package Name을 기반으로 판별
1. 원스토어의 마켓 서명을 통해 배포되지 않은 경우, PackageManager.getInstallerPackageName() API를 이용하여 앱 설치 시 사용된 스토어 정보를 확인합니다.
개발자 옵션(onestore:dev_option)이 활성화된 경우
1. onestore:dev_option 이 설정 되어있으면 무조건 StoreType.ONESTORE로 응답합니다.

활용 예시

스토어별 UI 차별화 적용
- 원스토어와 다른 앱 마켓에서 제공하는 결제 시스템이 다를 경우, UI를 다르게 설정할 수 있습니다.

if (StoreEnvironment.getStoreType() == StoreType.ONESTORE) {
    showOneStorePaymentUI()
} else {
    showDefaultPaymentUI()
}

스토어별 기능 차단
- 특정 기능을 원스토어에서만 사용하도록 설정할 수 있습니다.

if (StoreEnvironment.getStoreType() != StoreType.ONESTORE) {
    println("이 기능은 ONE Store에서만 사용할 수 있습니다.")
    return
}
enableOneStoreExclusiveFeature()

서버 API

도메인

기존에 대한민국에만 서비스하고 있는 경우 도메인 변경이 필요합니다.
- 대한민국에만 서비스하는 경우 : https://apis.onestore.co.kr
- 대한민국 이외의 국가/지역을 포함하여 서비스하는 경우 : https://iap-apis.onestore.net

마켓 구분

Request header에 마켓 구분 코드 (x-market-code)가 추가 되었습니다.
대한민국 외 국가/지역에 서비스 되는 경우 마켓 구분 코드를 헤더에 추가하여 요청해야 합니다.
마켓 구분 코드가 없는 경우에는 원스토어(기본값)로 호출됩니다.

<예제>

curl --location '{global domain}/v7/apps/com.sample/purchases/inapp/products/{productId}/{purchaseToken}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--header 'x-market-code: {marketCode}' \

마켓 구분 코드

서비스 국가 및 지역

MKT_ONE

대한민국

MKT_GLB

대한민국 이외

PNS

PNS의 경우 대한민국과 그 외 국가/지역의 메시지 발송 주소가 다릅니다.

따라서 방화벽을 사용하고 계신 경우, 각각의 발송 주소에 대해 방화벽 예외 처리가 필요합니다.

외부결제

서버 API

외부결제 API 버전이 V6로 변경되었습니다.
대한민국 외 국가/지역에서 서비스하는 경우 도메인 변경이 필요합니다.
- 대한민국에만 서비스하는 경우 : https://apis.onestore.co.kr
- 대한민국 이외의 국가/지역을 포함하여 서비스하는 경우 : https://iap-apis.onestore.net
외부결제 구매내역 전송 API의 Request Body에 국가/지역 정보와 통화코드가 추가 되었습니다.
외부결제 거래내역 전송 시 결제가 발생한 통화와 금액으로 전송해야 합니다.
외부결제 구매내역 전송 API가업데이트 되었습니다. (send3rdPartyPurchase-p1)
미국에서 발생한 외부결제 거래내역 전송 시 반드시 send3rdPartyPurchase-p1 규격으로 거래내역을 전송해야 합니다.
기존 규격은 미국 외 국가/지역에선 수정 없이 사용 할 수 있으나 deprecated 예정이므로, 신규 규격을 적용해주세요.

정산

원스토어 개발자센터 가입 시, 등록한 국가/지역 기준으로 서비스 이용료를 송금해야 합니다.
- 회원 국가/지역이 대한민국인 경우, 원화(KRW)로 송금해야 합니다. (단, 미국 판매분의 경우 해당 국가/지역의 서비스 제공자가 지정한 별도 계좌에 달러(USD)로 송금해야 합니다.)
- 회원 국가/지역이 대한민국 외인 경우, 달러(USD)로 송금해야 합니다. (단, 미국 판매분의 경우 해당 국가/지역의 서비스 제공자가 지정한 별도 계좌에 달러(USD)로 송금해야 합니다.)
서비스 이용료 산정에 적용되는 환율은 판매월 익월의 1일자 환율(서울외국환중개 고시 기준, 단 1일이 공휴일인 경우 전 영업일 환율)입니다.

상품

정기 결제

대한민국 외 국가/지역에서는 정기 결제 상품이 제공되지 않습니다.
기존에 정기 결제 상품이 등록되어 있더라도, 대한민국 외 국가/지역에는 배포되지 않습니다.
배포 국가/지역 및 현지 가격 설정, 다국어 설정은 상품등록과 관리를 참고하세요.

Last updated 8 days ago