글로벌 배포를 위한 가이드

용어

• 원스토어 : '대한민국'에 서비스하는 안드로이드 애플리케이션 스토어입니다.

• 글로벌 플랫폼: '대한민국'외 국가 및 지역에 서비스하는 안드로이드 애플리케이션 스토어입니다.

원스토어 서비스 구성

• 개발자는 원스토어 개발자센터에 한 번의 상품 등록으로 한국과 글로벌 모두에 상품을 판매할 수 있습니다.

  • 기존 한국 원스토어에 상품을 등록하여 판매하고 있던 개발자는 글로벌 배포를 선택하기만 하면 됩니다.

  • 원스토어 개발자센터는 개발자가 등록한 앱을 Re-Packaging하여 글로벌 서비스용 APK를 생성하고, 이를 글로벌 원스토어 사용자에게 배포합니다.

• 원스토어 클라이언트와 서버는 한국용과 글로벌용이 별도로 구성되어 있습니다.

  • App에서 IAP SDK API를 호출하면 서비스 국가/지역에 맞는 원스토어 클라이언트/서버와 자동으로 연동됩니다.

  • 개발사 서버에서 IAP Server API를 호출하는 경우, 마켓 구분코드(x-market-code)를 전달해야 합니다.

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

구분	Installer Package Name	마켓 구분 코드
대한민국	com.skt.skaf.A000Z00040 com.kt.olleh.storefront com.lguplus.appstore	MKT_ONE
글로벌	com.onestorecorp.gaa.storeapp com.dti.folderlauncher	MKT_GLB

SDK

SDK 버전

• 글로벌 플랫폼 배포를 위해서는 원스토어 인앱결제 SDK V19 (API V6) 이상이 적용되어야 합니다.

• SDK V17을 이용 중인 경우 SDK를 업그레이드 하셔야 합니다.

• SDK V16을 이용 중인 경우 SDK V21 이상이 적용된 앱을 새로 등록 하셔야 합니다.

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

• SDK V19.01 가이드

• SDK V21.01 가이드

원스토어 클라이언트 연동

• 대한민국에서 서비스되는 원스토어와 그 외 국가/지역에서 서비스되는 글로벌 플랫폼은 별도의 클라이언트 앱으로 서비스 됩니다.

• 대한민국에서 서비스 되는 앱은 '원스토어'로 그 외 국가/지역에서 서비스되는 앱은 글로벌 플랫폼과 연동 됩니다.

• 기존에 원스토어에서 서비스 되고 있는 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

서버 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 규격으로 거래내역을 전송해야 합니다.

• 기존 규격은 미국 외 국가/지역에선 수정 없이 사용 할 수 있으나 2025년 6월 경 deprecated 예정이므로, 신규 규격을 적용해주세요.

정산

• 원스토어 개발자센터 가입 시 등록한 국가/지역 기준으로 서비스 이용료를 송금해야 합니다.

  • 회원 국가가 대한민국이라면 원화로 송금해야 합니다. (단, 미국 판매분의 경우 해당 국가의 서비스제공자가 지정한 별도 계좌에 USD로 송금해야 합니다.)

  • 회원 국가가 대한민국 외 국가/지역이라면 USD로 송금해야 합니다. (단, 미국 판매분의 경우 해당 국가의 서비스제공자가 지정한 별도 계좌에 USD로 송금해야 합니다.)

• 서비스이용료 산정에 적용되는 환율은 판매월 익월의 1일자 환율 (서울외국환중개 고시 기준, 단 1일이 공휴일인 경우 전 영업일 환율)입니다.

상품

정기 결제

• 글로벌 플랫폼에서는 정기 결제 상품이 제공되지 않습니다.

• 기존에 정기 결제 상품이 등록되어 있더라도, 글로벌 플랫폼에는 배포되지 않습니다.

• 배포 국가/지역 및 현지 가격 설정, 다국어 설정은 상품등록과 관리를 참고하세요.