Unreal에서 원스토어 인앱결제 사용하기

개요

Unreal 개발환경에서 원스토어 인앱결제를 간편하게 적용 할 수 있도록 원스토어 Unreal Plugin을 제공합니다.

해당 플러그인은 Unreal 4.25 버전으로 개발 되었습니다.

Unreal Plugin 구성

Unreal Plugin은 다음과 같이 구성되어 있습니다.

assets : 원스토어 SDK가 사용하는 global-appstores.json 파일이 위치합니다. 해당 파일은 빌드 시, Android Assets으로 이동되어 apk에 포함됩니다.

lib : 원스토어 인앱 SDK와 Unreal 사용을 돕기 위한 Adapter 라이브러리가 위치합니다. 해당 파일은 빌드 시, jar lib로 이동되어 apk에 포함됩니다.

ONEStoreIap_UPL.xml : 빌드 시, GameActivity 및 Gradle 정보를 수정합니다.

OneStoreIap.Build.cs : Android 빌드 시, ONEStoreIap_UPL.xml을 로드 할 수 있도록 제공합니다.

응답 규격

Product

Unreal SDK에서 Product 정보는 다음과 같이 전달됩니다.

해당 내용은 Public/OneStoreIapInterface.h에 FOneStoreIapProductData struct로 정의되어 있습니다.

Original Product Json	원스토어로 부터 전달받은 파싱 전 Json String
Product Id	개발자센터를 통해 등록한 상품아이디
Type	인앱 상품의 타입 ("inapp" or "auto")
Price	인앱 상품의 가격 정보
Price Currency Code	인앱 상품의 통화 정보
Price Amount micros	인앱 가격 * 100만
Title	개발자센터를 통해 등록한 Product Name

Purchase

Unreal SDK에서 Purchase 정보는 다음과 같이 전달됩니다.

해당 내용은 Public/OneStoreIapInterface.h에 FOneStoreIapPurchaseData struct로 정의되어 있습니다.

Original Purchase Data	원스토어로부터 전달받은 파싱 전 Json String
Signature Data	원스토어로부터 전달받은 Signature String
Order Id	결제ID
Package Name	구매한 앱의 패키지명
Product Id	개발자센터를 통해 등록한 상품 아이디
Purchase Time	구매 시간
Acknowledge State	구매확인 상태( 0: Not Acknowledged, 1: Acknowledged)
Developer Payload	연동 회원사 서버에서 생성 관리하는주문 번호
Purchase Id	원스토어에서 발행한 개별 결제 ID
Purchase Token	원스토어에서 발행한 자동 결제 ID
Billing Key	자동 결제에 사용되는 billingKey 정보 (Option)

Unreal Blueprint for OneStore IAP

원스토어 Unreal Plugin은 다음과 같은 Blueprint를 제공합니다.

다음부터는 각 Blueprint에 대한 설명입니다.

One Store Disconnect

원스토어와 연결은 각 API를 호출하면 자연스럽게 진행됩니다.

다만 연결 종료의 경우 화면의 라이프 사이클에 따라 호출이 필요합니다.

One Store Iap Get Product Details

원스토어에 등록된 상품의 상세 정보를 요청합니다.

관리형 상품의 경우 Product Type에 "inapp" 으로 월정액 상품의 경우 "auto"로 규격을 호출하면 됩니다.

앱간 호출의 경우 메모리 이슈가 있을 수 있으니 20 ~ 30개씩 끊어 조회하는 것을 추천합니다.

Request Params

Product Type	관리형 상품("inapp") or 월정액 상품("auto")
Product List	상품 상세를 조회할 상품의 Product Id(String)의 list

Response Type

On Success	상품 상세 조회 성공 시 호출 됨
On Failure	상품 상세 조회 실패 시 호출 됨
On Need Update	원스토어 결제 모듈의 업데이트 필요 시 호출 됨
On Need Login	원스토어 로그인 필요 시 호출 됨

Response Params

Result Code	성공 : 0 / 실패 시 에러코드를 전달 (에러 코드는 기존 가이드 참조)
In App Product Info List	성공 시, 조회를 요청한 상품의 상세 data(FOneStoreIapProductData)의 리스트를 전달

One Store Iap Purchase Info

소비(consume)되지 않은 관리형 상품과 월정액 상품의 구매 이력 조회가 가능합니다.

Product Type에 관리형 상품 또는 월정액 상품을 지정하여 조회를 진행하면 됩니다.

Request Params

Product Type

관리형 상품("inapp") or 월정액 상품("auto")

Response Type

On Success	구매 이력 조회 성공 시 호출 됨
On Failure	구매 이력 조회 실패 시 호출 됨
On Need Update	원스토어 결제 모듈의 업데이트 필요 시 호출 됨
On Need Login	원스토어 로그인 필요 시 호출 됨

Response Params

Result Code	성공 : 0 / 실패 시 에러코드를 전달 (에러 코드는 기존 가이드 참조)
One Store Iap Purchase Data List	성공 시, 조회를 요청한 상품의 상세 data(FOneStoreIapPurchaseData)의 리스트를 전달

One Store Iap Request Purchase

원스토어 인앱 결제를 요청합니다.

Request Params

Product Type	관리형 상품("inapp") or 월정액 상품("auto")
Product Id	개발자센터를 통해 등록한 상품아이디
Product Name	결제 화면에 노출 할 상품명 (공백일 경우 개발자센터에 등록된 상품명 노출)
Dev Payload	연동 회원사 서버에서 생성 관리하는주문 번호 입력 할 경우 Consume & Acknowledge에서도 동일한 값을 입력해야 함

Response Type

On Success	결제 성공 시 호출 됨
On Failure	결제 실패 시 호출 됨
On Need Update	원스토어 결제 모듈의 업데이트 필요 시 호출 됨
On Need Login	원스토어 로그인 필요 시 호출 됨

Response Params

Result Code	성공 : 0 / 실패 시 에러코드를 전달 (에러 코드는 기존 가이드 참조)
Purchase Data	성공 시, 결제 성공 한 상품의 상세 data를 전달

One Store Iap Consume Purchase

재구매가 필요한 소비성 상품은 구매에 성공한 후 소비(Consume) 및 아이템 지급을 진행해야 합니다.

소비 처리가 되지 않으면, 해당 상품은 다시 구매가 되지 않습니다.

원스토어 인앱결제 SDK V19부터 3일 이내에 소비(consume) 또는 구매 확인(ackowledge)를 하지 않을 경우 아이템이 지급되지 않은 것으로 판단되어 해당 구매는 취소됩니다.

Request Params

Purchase Data	결제 및 구매 이력 조회 시, 전달받은 구매 전문 String
Dev Payload	연동 회원사 서버에서 생성 관리하는주문 번호 결제 시 입력한 dev payload와 동일해야 함(결제 시 미 사용 하였다면 고유 값 입력 가능)

Response Type

On Success	소모 성공 시 호출 됨
On Failure	소모 실패 시 호출 됨
On Need Update	원스토어 결제 모듈의 업데이트 필요 시 호출 됨
On Need Login	원스토어 로그인 필요 시 호출 됨

Response Params

Result Code	성공 : 0 / 실패 시 에러코드를 전달 (에러 코드는 기존 가이드 참조)
Original Purchase Data	Consume을 요청한 Purchase Data를 그대로 리턴 함

One Store Iap Acknowledge Purchase

구매에 성공한 상품에 대한 구매 확인 기능으로 영구성으로 사용할 관리형 상품이나 월정액 상품의 경우에는 acknowledge를 호출해야 합니다.

원스토어 인앱결제 SDK V19부터 3일 이내에 소비(consume) 또는 구매 확인(ackowledge)를 하지 않을 경우 아이템이 지급되지 않은 것으로 판단되어 해당 구매는 취소됩니다.

Request Params

Purchase Data	결제 및 구매 이력 조회 시, 전달받은 구매 전문 String
Dev Payload	연동 회원사 서버에서 생성 관리하는주문 번호 결제 시 입력한 dev payload와 동일해야 함(결제 시 미 사용 하였다면 고유 값 입력 가능)

Response Type

On Success	구매 확인 성공 시 호출 됨
On Failure	구매 확인 실패 시 호출 됨
On Need Update	원스토어 결제 모듈의 업데이트 필요 시 호출 됨
On Need Login	원스토어 로그인 필요 시 호출 됨

Response Params

Result Code	성공 : 0 / 실패 시 에러코드를 전달 (에러 코드는 기존 가이드 참조)
Original Purchase Data	Acknowledge을 요청한 Purchase Data를 그대로 리턴 함 구매 데이터의 Acknowledge상태 변경을 확인 하기 위해서는 Get Purchase Data를 이용

One Store Iap Manage Recurring

월정액 상품의 상태를 변경 합니다.

상태의 경우 cancel or reactivate 2가지 상태이며 cancel의 경우 다음 결제일에 자동 결제를 진행하지 않습니다.

Request Params

Purchase Data

결제 및 구매 이력 조회 시, 전달받은 구매 전문 String

Response Type

On Success	월정액 상품 상태 변경 성공 시 호출 됨
On Failure	월정액 상품 상태 변경 실패 시 호출 됨
On Need Update	원스토어 결제 모듈의 업데이트 필요 시 호출 됨
On Need Login	원스토어 로그인 필요 시 호출 됨

Response Params

Result Code	성공 : 0 / 실패 시 에러코드를 전달 (에러 코드는 기존 가이드 참조)
Action	상태 변경 (cancel / reactivate) cancel : 월정액 정기결제 해제 예약 reactivate : 해지 예약 상태를 원상태로 회복
Original Purchase Data	상태 변경을 요청한 구매 데이터 원본

One Store Iap Get Store Code

v19의 경우 S2S API에서 이용 가능 한 마켓 구분 코드를 전달하는 API를 제공한다.

Response Type

On Success	마켓 구분 코드 규격 호출 성공 시 호출 됨
On Failure	마켓 구분 코드 규격 호출 실패 시 호출 됨
On Need Update	원스토어 결제 모듈의 업데이트 필요 시 호출 됨
On Need Login	원스토어 로그인 필요 시 호출 됨

Response Params

Result Code	성공 : 0 / 실패 시 에러코드를 전달 (에러 코드는 기존 가이드 참조)
Store Code	스토어 고유 값을 리턴 (ex 원스토어 : MKT_ONE)

One Store Iap Request Login

위 규격의 Response Type 중 On Need Login이 호출 될 시, 원스토어 로그인이 처리를 위해 사용됩니다.

Response Type

On Success	로그인 성공 시 호출 됨
On Failure	로그인 실패 시 호출 됨

Response Params

Result Code

성공 : 0 / 실패 시 에러코드를 전달 (에러 코드는 기존 가이드 참조)

One Store Iap Request Update

위 규격의 Response Type 중 On Need Update가 호출 될 시, 원스토어 업데이트 처리를 위해 사용됩니다.

Response Type

On Success	업데이트 성공 시 호출 됨
On Failure	업데이트 실패 시 호출 됨

Response Params

Result Code

성공 : 0 / 실패 시 에러코드를 전달 (에러 코드는 기존 가이드 참조)

One Store Purchase Verify

구매 데이터의 검증을 지원하는 API로 개발자센터에서 발급 받은 라이센스 key (Public key)를 통해 Signature와 Purchase Data를 검증합니다.

다만 서버 검증을 할 경우는 해당 API를 사용하기 보다는 서버 아이템 검증을 진행하는 것을 추천드립니다.

Request Params

Public Key	개발자센터에서 발급 받은 라이센스 key (Public key)
Original Purchase Data	결제 or 미소비 구매 이력 API 호출 시 전달된 Purchase Data String
Signature data	결제 or 미소비 구매 이력 API 호출 시 전달된 Signature String

Response Params

Return Value

true : 검증 성공 false : 검증 실패

Sample Case

다음은 Blueprint를 이용하는 예제입니다. 반드시 예제대로 구현할 필요는 없으며, 공개된 Blueprint를 수정하여 알맞게 사용하면 됩니다.

관리형 상품 결제 및 소비 case

월정액 상품 결제 및 구매 확인 case

관리형 상품 구매이력 조회 및 소비 case

관리형 상품 구매이력 조회 및 구매 확인 case

구매이력 조회 및 월정액 상품 상태 변경 case

마켓 구분 코드 case

로그인 및 업데이트 처리 case