< 참고 >

본 문서는 원스토어 인앱 SDK v16(API v4)에 대한 가이드 문서입니다. 최신 원스토어 인앱 SDK v17(API v5)에 대한 가이드 문서는 원스토어 개발자센터에서 제공되고 있습니다.

최신 인앱 SDK v17 가이드 문서 링크 : https://dev.onestore.co.kr/devpoc/reference/view/IAP_v17

원스토어 개발자센터 IAP 내에서 판매할 수 있는 In-App Product(인앱 상품)의 유형은 건당 상품, 기간 상품, 정식판 전환 상품 등이 있으며, Application 기획 단계에서 Application이 제공하고자 하는 서비스의 특성을 고려하여 적합한 In-App Product의 유형을 선택해야 한다.

구매 후 사용할 수 있는 상품을 건당 상품이라고 하며, 구매한 상품의 영구 유지 여부에 따라 영구성 상품과 소멸성 상품으로 나뉜다.

• 구매 후 지정된 기간 동안만 사용 가능한 상품을 기간성 상품이라 하며, 상품의 이용 기간에 따라 아래 표와 같이 나뉜다.
• 해당 모든 상품은 단말 번호(MDN)를 기준으로 중복 구매가 불가능하다.
• 단, 구매한 상품의 기간이 만료되는 경우 해당 상품을 다시 구매할 수 있다.

무료로 배포되는 체험판 Application 내에서 In-App 결제를 하면, 유료의 정식판 Application으로 Lock 해제를 통해 전환할 수 있는 상품

Legacy 상품 타입 입니다. 사용을 권하지 않습니다.

IAP SDK는 7개의 Java 클래스(또는 인터페이스)들을 제공한다.

[표] com.skplanet.dodo 패키지

주요 함수는 다음과 같은 항목으로 설명한다.

Description

결제 또는 조회 요청을 위한, 새로운 IapPlugin 객체를 생성하여 반환한다.

호출시 필수 파라미터로 pluginmode 문자열을 넘겨줘야 한다. 정상적인 값을, 넘겨주지 않을 경우 상용 서버(release) 모드로 셋팅된다.

호출 시마다, 새로 생성한 객체를 돌려준다. 각 객체별로 서버 셋팅이 달라 질 수 있다.

Syntax

static final IapPlugin getPlugin(Context context, String pluginmMode)

Parameters

context

• Android Context, 해당 context의 경우 안드로이드 Activity context를 넣는 것을 추천

pluginmode

• String, 상용/개발 서버 설정용 문자열

• development : 개발 서버 (IapPlugin.DEVELOPMENT_MODE)

• release : 상용 서버 (IapPlugin.RELEASE_MODE)

Return 정상적으로 성공시에 IapPlugin 인스턴스를 리턴

Description

IapPlugin 인스턴스에 더 이상 접근하지 않을 경우(ex. 개발사 앱 종료 시) 호출 해주어야 한다. 미호출 시에는 메모리 누수가 발생 할 수도 있으므로 호출을 권장한다.

Syntax

void exit()

함수 호출 시에, 값들을 파라미터로 넘겨서 요청을 한다. 직접 요청전문을 String으로 만들지 않도록 해준다.

Description

결제를 요청한다. 호출 시에 필요한 PaymentParams값은 PaymentParams.Builder를 이용하여 만든다.

Syntax

String sendPaymentRequest(RequestCallback requestCallback, PaymentParams params)

Parameters

requestCallback

• 결제 요청에 대한 결과를 받을 콜백

params

• PaymentParams.Builder로 생성된 결제 요청 내용
• PaymentParams.Builder Parameter 설명

Return 정상적으로 요청 시에, 요청식별자(RequestId)를 반환

Description

구매내역 조회를 요청한다. 단일, 다중, 전체 상품에 대해서 조회가 가능하다.

Syntax

String sendCommandPurchaseHistory(RequestCallback requestCallback, ProcessType type, String appId, String... productIds)

Parameters

requestCallback

• 조회 요청에 대한 결과를 받을 콜백

type

• 요청에 대해서, Background(UI노출 없임)로만 처리 할지, 필요한 경우 Foreground(UI노출 허용)를 허용 할지를 결정
• ProcessType.BACKGROUND_ONLY
• ProcessType.FOREGROUND_IF_NEEDED

appId

• 조회를 하려는 상품(앱)의 ID

productIds

• 조회를 하려는 상품(인앱상품)의 ID
• 조회를 원하는 상품을 복수개 입력 가능
• null 입력 할 경우, 전체 상품(인앱상품)에 대해서 조회를 수행

Return 정상적으로 요청 시에, 요청식별자(RequestId)를 반환

Description

앱의 상품(인앱상품)정보 조회를 요청한다.

Syntax

String sendCommandProductInfo(RequestCallback requestCallback, ProcessType type, String appId)

Parameters

requestCallback

• 조회 요청에 대한 결과를 받을 콜백

type

• 요청에 대해서, Background(UI노출 없임)로만 처리 할지, 필요한 경우 Foreground(UI노출 허용)를 허용 할지를 결정
• ProcessType.BACKGROUND_ONLY
• ProcessType.FOREGROUND_IF_NEEDED

appId

• 조회를 하려는 상품(앱)의 ID

Return 정상적으로 요청 시에, 요청식별자(RequestId)를 반환

Description

구매 가능여부 조회를 요청한다. 단일, 다중 상품에 대해서 조회가 가능하다.

Syntax

String sendCommandCheckPurchasability(RequestCallback requestCallback, ProcessType type, String appId, String... productIds)

Parameters

requestCallback

• 조회 요청에 대한 결과를 받을 콜백

type

• 요청에 대해서, Background(UI노출 없임)로만 처리 할지, 필요한 경우 Foreground(UI노출 허용)를 허용 할지를 결정
• ProcessType.BACKGROUND_ONLY
• ProcessType.FOREGROUND_IF_NEEDED

appId

• 조회를 하려는 상품(앱)의 ID

productIds

• 조회를 하려는 상품(인앱상품)의 ID
• 조회를 원하는 상품을 복수개 입력 가능 (null 입력 불가)

Return 정상적으로 요청 시에, 요청식별자(RequestId)를 반환

Description

구매한 상품 상태 변경을 요청한다. 정액제 상품의 경우 가입 해지, 소멸성 상품의 경우 포인트 차감 등을 요청

Syntax

String sendCommandChnageProductProperties(RequestCallback requestCallback, ProcessType type, String appId, String action, String... productIds)

Parameters

requestCallback

• 조회 요청에 대한 결과를 받을 콜백

type

• 요청에 대해서, Background(UI노출 없임)로만 처리 할지, 필요한 경우 Foreground(UI노출 허용)를 허용 할지를 결정
• ProcessType.BACKGROUND_ONLY
• ProcessType.FOREGROUND_IF_NEEDED

appId

• 상태 변경을 하려는 상품(앱)의 ID

action

• cancel_subscription : 정액 가입 해지 요청 액션 (Action.cancel_subscription.action())
• subtract_points : 가용 포인트 차감 요청 액션 (Action.subtract_points.action())
• null 입력 불가

productIds

• 상태 변경을 하려는 상품(인앱상품)의 ID
• 상태 변경을 원하는 상품을 복수개 입력 가능 (null 입력 불가)

Return 정상적으로 요청 시에, 요청식별자(RequestId)를 반환

Description

전자 영수증 검증을 요청한다.

Syntax

void sendVerifyReceiptRequest(String appId, String txId, String signData, ReceiptVerificationTask.RequestCallback callback)

Parameters

txId

• 구매 결과로서 받은 TxID

appId

• 검증을 하려는 상품(앱)의 ID

signData

• 구매 결과로서 받은 영수증 (receipt)

callback

• 검증 요청에 대한 결과를 받을 콜백

직접 요청전문을 String으로 만들어서 요청을 한다.

Description

결제를 요청한다. 기존 버전에서 제공 하던 것으로, 하위 호환성을 위해서 제공한다.

Syntax

// 16.03
Bundle sendPaymentRequest(String appId, String pId, String productName, String tId, String bpInfo, RequestCallback requestCallback)

// 16.04 (gameUserId, promotionApplicable parameters 추가
Bundle sendPaymentRequest(String appId, String pId, String productName, String tId, String bpInfo, String gameUserId, boolean promotionApplicable, RequestCallback requestCallback)

Parameters

appId, pId, productName, tId, bpInfo, gameUserId, promotionApplicable

• product_name 은 한글은 50자, 영문은 100자까지 가능하나, 50자 이하를 권장함

• tid, product_name에서 쌍따옴표( ", double quotation ) 는 사용 불가
• tid 에서 띄어쓰기 불가

requestCallback

• 결제 요청에 대한 결과를 받을 콜백

Return 정상적으로 요청 시에, 요청식별자(RequestId)를 포함한 정보를 반환 (실패시에는 null을 리턴)

bundle의 Extra Key

• req.id : 요청식별자
• req.rescode : 요청에 대한 에러 코드
• req.resmsg : 요청에 대한 결과 메시지

IAP 서버는 구매 요청에 대한 결과를 JSON 형태의 응답 데이터를 생성하여 전송한다. 구매 처리에 대한 응답 데이터 형식은 다음과 같다.

결과 및 에러코드는 레퍼런스(Result-Code) 참조한다

인앱 상품명은 request 시점에 전달한 값을 리턴함 (없으면 개발자센터 등록명 사용) bp_info 는 json 응답으로는 리턴하지 않음??

[통신사별 TXID 부여 Sample]

{
	"api_version" : "(api version)", 
	"identifier" : "(request id)", 
	"method" : "purchase", 
	"result" : {
		"code" : "(result code)",
		"message" : "(result message)",
		"txid" : "(id)",
		"receipt" : "(encode receipt using Base64)", 
		"count" : "(count of product)",
		"product" : [ { "(product information)" } ]
		}
}

Description

여러가지 조회(요청)을 수행한다.

• 구매내역 조회
• 상품정보 가져오기
• 구매 가능여부 체크
• 구매한 상품 상태 변경 요청

Syntax

Bundle sendCommandRequest(String param, RequestCallback requestCallback)

Parameters

param

• 조회를 위한 json 포맷의 요청 전문

requestCallback

• 결제 요청에 대한 결과를 받을 콜백

Return 정상적으로 요청 시에, 요청식별자(RequestId)를 포함한 정보를 반환 (실패시에는 null을 리턴)

bundle의 Extra Key

• req.id : 요청식별자
• req.rescode : 요청에 대한 에러 코드
• req.resmsg : 요청에 대한 결과 메시지

Method 종류

• action: cancel_subscription 정액 가입 해지 요청 액션

• action: subtract_points 가용 포인트 차감 요청 액션

하위 호환용 method

아래 method는 구버전 IAP에서 사용한 규격으로 사용을 권장하지 않음

|Method|Description|Req Parameters| |-----|-----|-----| |auth_item |구매한 단일/다중 상품 조회 요청|appid, product_id| |whole_auth_item |구매한 모든 상품 조회 요청 |appid| |monthly_withdraw |월 정액 해지 요청 |appid, product_id| |item_use |소멸성 상품 포인트 차감 요청 |appid, product_id|

{
	"method" : "(method name)", 
	"param" : {
		"appid" : "(application id)", 
		"product_id" : ["(product id)"], 
		"action" : "(sub action of method)" 
		}
}

결과 및 에러코드는 레퍼런스(Result-Code) 참조한다

주의사항

• 월정액 상품[auto-renewal-month] 인 경우 사용 가능한 일수로 사용하지 말아야 하며 endDate 기준으로 Application 에서 확인후 사용한다.
• status 는 아래 메소드 응답일 경우에만 필수로 결과코드와 메시지를 리턴한다.
  • request_purchase_history
  • change_product_properties
    
    
  • auth_item
  • item_use
  • monthly_withdraw

응답 데이터 기본 형식

{
	"api_version" : "(api version)", 
	"identifier" : "(request id)", 
	"method" : "purchase", 
	"result" : { 
		"code" : "(result code)", 
		"message" : "(result message)" 
   }
}

조회성 qurey의 응답 데이터 형식 조회성 커맨드 요청일 경우 응답 데이터 result 필드 안에 product 필드가 포함되며 product 필드 안에 포함되는 필드 정보는 각 기능 메소드 별로 상이하다

{
	"api_version" : "(api version)", 
	"identifier" : "(request id)", 
	"method" : "purchase", 
	"result" : {
		"code" : "(result code)",
		"message" : "(result message)",
		"count" : "(count of product)",
		"product" : [ { "(product information)" } ] 
	}
} 
 

위와 동일한 기능이며, Foreground허용 여부를 결정 할 수 있십니다.

Description

여러가지 조회(요청)을 수행한다.

• 구매내역 조회
• 상품정보 가져오기
• 구매 가능여부 체크
• 구매한 상품 상태 변경 요청

Syntax

Bundle sendCommandRequest(String param, RequestCallback requestCallback, ProcessType type)

Parameters

param

• 조회를 위한 json 포맷의 요청 전문

requestCallback

• 결제 요청에 대한 결과를 받을 콜백

type

• 요청에 대해서, Background(UI노출 없임)로만 처리 할지, 필요한 경우 Foreground(UI노출 허용)를 허용 할지를 결정
• ProcessType.BACKGROUND_ONLY
• ProcessType.FOREGROUND_IF_NEEDED

Return 정상적으로 요청 시에, 요청식별자(RequestId)를 포함한 정보를 반환 (실패시에는 null을 리턴)

요청 결과를 받기 위한 추상 클래스이다. 해당 클래스를 구현하고, 객체를 생성하여 요청 시에 매개변수로 넘겨야 한다.

private IapPlugin.AbsRequestCallback mAbsRequestCallback = new IapPlugin.AbsRequestCallback() {
        @Override
        protected void onResponse(Response response) {
            // 정상적인 응답을 받음
        }

        @Override
        public void onError(String reqid, String errcode, String errmsg) {
            // 에러발생
        }
    };

AbsRequestCallback 은 아래와 같은 메서드를 제공한다.

Description

요청 처리 중 실패하면 호출되는 콜백

onError 에러 코드, 메시지 정의는 레퍼런스(Result-Code) 참조한다.

Syntax

void onError(String reqid, String errcode, String errmsg)

Parameters

• reqid 요청 아이디
• errcode 실패 코드
• errmsg 실패 메시지

Description

정상적으로 요청 처리결과를 응답 받은 경우 호출되는 콜백

Syntax

void onResponse(Response response)

응답 클래스 (결과를 객체 형태로 가지고 있음)이다. IapResultCallback의 onResponse 호출(콜백) 시에 매개변수로 전달 된다.

이 클래스는 서버로 부터 받은 String형태의 결과를 클래스의 형태로 변환한 것이다. 기존에는 샘플프로젝트의 helper 패키지를 통해서 개발자가 직접 변환하였으나, 이번 버전 부터는 변환 후 결과를 주는 것으로 수정 되었다.

모든 필드는 public으로서 직접 접근이 가능하다. 모든 필드는 null 일 수 있다. 서버로 부터 정보를 받지 못한 부분에 대해서는 기본적으로 null이 셋팅 된다.

public class Response {
    public final String api_version;
    public final String identifier;
    public final String method;
    public final Result result;
    ...
}

public static class Result {
    public final String message;
    public final String code;
    public final String txid;
    public final String receipt;
    public final Integer count;
    public final List<Product> product;
    ...
}

public static class Product {
    public String appid;
    public String id;
    public String name;
    public String type;
    public String kind;
    public Integer validity;
    public Double price;
    public String startDate;
    public String endDate;
    public Boolean purchasability;
    public Status status;
    ...
}

public static class Status {
    public String code;
    public String message;
    ...
}

요청 처리 타입을 정의한 enum이다.

public enum ProcessType {
    BACKGROUND_ONLY,
    FOREGROUND_IF_NEEDED,
}

기본적으로 FOREGROUND_IF_NEEDED을 설정을 추천한다.

요청 처리 과정에서 Ui 노출이 필요한 경우가 있다. 예를 들어,

• 퍼미션 요구 화면
• ONE store service 설치 요구 화면

위와 같은 상황들이 존재한다. 이런 상황에 대해서 요청을 중지 시키고 에러를 받고 싶다면, BACKGROUND_ONLY로 요청을 하면 된다.

IapPlugin의 호출을 통한, 결과를 받기 위한 Callback 인터페이스이다.

요청 메서드 호출 시, 구현된 RequestCallback 인스턴스를 파라미터로 전달함으로 콜백이 설정되며 요청 처리 실패, 성공에 따라 해당하는 인터페이스 메서드가 호출 된다.

RequestCallback 은 아래와 같은 메서드를 제공한다.

Description

요청 처리 중 실패하면 호출되는 콜백

onError 에러 코드, 메시지 정의는 아래 항목을 참고한다.

Syntax

void onError(String rid, String errcode, String errmsg)

Parameters

• rid 요청 아이디
• errcode 실패 코드
• errmsg 실패 메시지

Description

정상적으로 요청 처리결과를 응답 받은 경우 호출되는 콜백

onResponse 결과 코드, 메시지 정의는 레퍼런스(Result-Code) 참조한다.

Syntax

public void onResponse(IapResponse response)

Parameters

response IapResponse 구현한 응답 데이터 인스턴스로 목록은 아래와 같다.

서버 응답 데이터에 대한 인터페이스로 메서드 목록은 아래와 같다.

Description

응답 데이터 길이를 반환한다.

Syntax

long getContentLength())

Return

응답 데이터 길이

Description

응답 데이터를 InputStream로 반환한다.

Syntax

InputStream getContent() throws IOException 

Return

응답 데이터를 읽을 수 있는 InputStream을 리턴

Description

응답 데이터를 String으로 반환한다. 문자열은 getContentEncoding 반환되는 인코딩 방식으로 변환된다. (기본 인코딩 방식은 utf-8 이 사용된다)

Syntax

String getContentToString()

Return

인코딩되어진 결과를 String으로 리턴

Description

문자 데이터 인코딩 타입을 반환한다. (기본 인코딩 방식은 utf-8이 사용된다.)

Syntax

String getContentEncoding()

Return 인코딩 타입을 String으로 반환한다.