NAS STORE SDK 연동 가이드
. 개요
이 문서는 NAS STORE SDK 연동을 위한 문서입니다.
. 개발자 등록
NAS 오퍼월 연동을 위해서는 먼저 개발자 등록을 해야합니다.
NAS 홈페이지에 접속하여 상단의 "개발자" 메뉴를 클릭하고 "회원가입" 버튼을 눌러 가입합니다.
. 앱 등록
NAS STORE SDK 연동을 위해서는 연동할 앱을 등록 해야합니다.
NAS 홈페이지에 로그인 후 상단의 "개발자" 메뉴로 들어가 “앱 등록” 버튼을 눌러 앱을 등록합니다.

앱 등록시


위 이미지에서 보시는 것과 마찬가지로 붉은색으로 표시된 영역만 입력하시면 됩니다.
앱을 등록하면 32자리 앱 KEY앱 스토어 KEY가 발급되며, SDK 초기화 시 필요한 값입니다.
개발자 메뉴의 앱 목록에서 각 앱의 "앱 KEY" 버튼을 클릭하면 앱 KEY를 확인할 수 있습니다.
"앱 스토어 KEY"의 경우, 담당자를 통해 전달 받으실 수 있습니다.
. SDK Info Setting
SDK 정상적인 사용을 위해서는 기본 정보 셋팅이 반드시 필요합니다.
SDK 정보 수정정 페이지의 상단에 APP_KEYAPP_STORE_KEY를 입력하신 후, 하단에 표시되는 기본 정보를 입력해 주세요.
구매 테스트를 위해서는 *구매 콜백 URL을, 환불 테스트를 위해서는 *환불 콜백 URL을 정상 입력하셔야 테스트 진행이 가능합니다.
. SDK 연동
- SDK 다운로드
- 예제 프로그램 다운로드

NAStore.jar 파일을 프로젝트의 libs 폴더에 복사합니다.

❈ 스토어 SDK 에는 이미 Proguard가 적용되어 있습니다. Proguard 적용 시 스토어 SDK는 제외시켜 주셔야 정상 작동합니다

. AndroidManifest.xml 설정
AndroidManifest.xml 에 다음 권한을 추가합니다.
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

❈ 프로젝트의 Target SDK를 23(Android 6.0) 이상으로 지정 한 경우, 사용자가 위의 권한을 허가하지 않으면 스토어가 정상적으로 작동하지 않을 수 있습니다.
안드로이드 6.0 이상에서는 스토어를 사용하기전에 위의 권한들이 모두 허용되어 있는지 먼저 확인 후 사용하시기 바랍니다. 만약 권한이 없다면 사용자에게 권한 요청을 하시기 바랍니다.
사용자에게 권한을 요청하는 방법은 다음 공식 문서를 참고하세요.

http://developer.android.com/intl/ko/training/permissions/requesting.html

AndroidManifest.xml에 앱 Key를 설정합니다.
[APP_KEY]부분을 앱 등록 후 받은 키로 대체합니다.
[APP_STORE_KEY]부분을 앱 등록 후 받은 키로 대체합니다.
<meta-data android:name="nastore_app_key" android:value="[APP_KEY]" />
<meta-data android:name="nastore_app_store_key" android:value="[APP_STORE_KEY]" />

AndroidManifest.xml 의 application 에 다음 Activity 정보를 추가합니다.
<activity
android:name="com.metapsplus.sdk.store.NAStore"
android:configChanges="keyboardHidden|orientation|screenSize"
android:screenOrientation="portrait"/>
. 상점 띄우기
USER_DATA 는 개발자가 사용자를 구분하기 위한 값 입니다.
사용자가 광고 참여 완료 후 개발자 서버로 콜백 URL이 호출될 때 [USER_DATA] 파라메터로 전달됩니다.

스토어 Activity가 종료된 경우 NAStoreListener.OnClose() 이벤트가 발생합니다.
사용자가 상품구매를 성공한 경우 NAStoreListener.OnPointReload() 이벤트가 발생합니다.

* USER_DATA는 varchar(50)의 자릿수로 제한됩니다.

Activity activity = this;
String userData = "USER_DATA";
int userMoney = 0;

NAStore.open(activity, userData, userMoney, new NAStoreListener() {

@Override
public void OnClose() {
    //스토어 Activity가 종료된 경우.
}

@Override
public void OnPointReload() {
    //사용자가 상품구매를 성공한 경우.
    //사용자가 상품환불을 성공한 경우.
    //보통 OnPointReload 리스너가 들어오면 앱에서 보여주는 사용자적립금을 갱신 합니다.
}

});
. 결제 프로세스 - TYPE A
* 사용 내역 관리를 개발사에서 직접 할 경우에 해당하는 결제 프로세스 입니다.

* 다음 이미지는 SDK 연동 후 실 결제 행위를 기반으로 표현된 결제 프로세스 입니다.



1. SDK 호출
"4. SDK 연동"을 통해서 SDK를 호출 해 주세요.
4. 매체사 CALL BACK URL 호출 / 5. 매체사 구매 처리
콜백 URL은 NAS STORE 서버에서 개발자 서버로 호출하는 URL로 사용자가 스토어 SDK에서 상품 구매 시 호출됩니다.
콜백 URL에서 사용자에게 적립금 차감 및 구매 내역 리스트를 구성하시기 바랍니다.

콜백 URL 에는 아래의 값들이 제공됩니다.

이 값들은 개발자 서버로 호출 시 실제 값으로 변환됩니다.
콜백 URL 입력 시 반드시 대괄호까지 입력하시기 바랍니다.
아래의 사용예를 참고해주시기 바랍니다.

[USE_ID] : 결제 Unique 키값. 상세 데이터 호출 및 환불 시 사용.
[PRICE] : 상품 금액
[USE_TYPE] : 상품 구분 (1:기프티 쿠폰)
[USE_STATUS] : 2-구매, 3-환불
[USE_TITLE] : 상품 명
[USER_DATA] : 회원 정의 데이터

ex) http://test.co.rk/test.asp?UID=[USE_ID]&P=[PRICE]&UTYPE=[USE_TYPE]&US=[USE_STATUS]&UTITLE=[USE_TITLE]&UD=[USER_DATA]

구매 처리 결과값
개발자 서버에서 구매 처리가 끝난 후 JSON 타입으로 "result"와 "money"를 리턴해주시면 됩니다.
성공 - {"result":"1", "money":1000}
실패 - {"result":"0"}
result값은 1일때만, 정상 처리 되면, 구매가 실패 했을 시에는 0으로 내려주시면 됩니다.
money는 화면에 보여주는 사용자 금액으로 구매 처리후 남은 잔액을 내려주시면 됩니다. 해당 금액은 보여주는 용도로만 사용되며, 구매처리시 따로 체크를 하지는 않습니다.

"3. 구매 STEP 1"은 임시 구매에 해당하고, 실제 구매 처리는 개발자 서버의 구매 처리가 완료 된 후 "6. 구매 STEP 2"에서 진행이 됩니다.
개발자 서버의 금액 차감은 "3. 구매 STEP 1"에서 1차적으로 이루어지지만, "6. 구매 STEP 2"에서 성공처리 되지 않으면, 차감된 금액이 복구 됩니다.

❈ 적립금 중복 차감 방지를 위한 처리
1. 콜백 중복 호출 시, 적립금 중복 차감을 방지하기 위해, [USE_ID]를 기준으로 중복 차감을 막아주시기 바랍니다.
8. ~ 9. 상세 구매 데이터 호출
4. 매체사 CALL BACK URL 호출 / 5. 매체사 구매 처리에서 구매 처리한 상품의 상세 데이터를 받아오는 API로 처리 결과는 JSON 으로 리턴됩니다.

- URL
http://www.appang.kr/STORE/lock/StoreBuyDataProc.asp

- 파라메터 (*=필수항목)
aidkey * 앱 KEY
aidpwd * 앱 스토어 KEY
use_id * [USE_ID] - 결제 Unique 키값
ud * [USER_DATA] - 회원 정의 데이터

- 결과
result 1 : 성공
-100 : 환불 처리 할 것
-99999 : 파라메터 오류로 인해 데이터 호출 실패
result 값이 1일 경우에만 아래 데이터가 나옴.
use_type 상품 형태
1 : 기프티쇼
6 : 현금신청
*[기프티쇼] use_type = 1 일 경우
use_status 결제 상태
2 : 구매
3 : 환불

* 2일 때, 쿠폰 사용 여부에 따라 환불이 가능함
use_title 상품명
use_img 상품 이미지
use_end_date 구매 상품 유효 기간
use_coupon_img 기프티쇼 쿠폰 이미지
*[현금신청] use_type = 6 일 경우
use_status 결제 상태
1 : 신청
2 : 구매
3 : 환불
5 : 대기

* 신청 상태 일때만, 환불이 가능. 대기는 입금 대기중을 말함.
money 현금 신청 금액 (매체사 환율 적용 금액)
vat 현금 신청 수수료 (매체사 환율 적용 금액)
ori_money 현금 신청 금액 (원가 금액)
ori_vat 현금 신청 수수료 (원가 금액)
bank 은행명
bank_number 계좌번호
bank_account 예금주
. 결제 프로세스 - TYPE B
* 사용 내역 관리를 NAS STORE 서버에서 할 경우에 해당하는 결제 프로세스 입니다.

* 다음 이미지는 SDK 연동 후 실 결제 행위를 기반으로 표현된 결제 프로세스 입니다.



1. SDK 호출
"4. SDK 연동"을 통해서 SDK를 호출 해 주세요.
4. 매체사 CALL BACK URL 호출 / 5. 매체사 구매 처리
콜백 URL은 NAS STORE 서버에서 개발자 서버로 호출하는 URL로 사용자가 스토어 SDK에서 상품 구매 시 호출됩니다.
콜백 URL에서 사용자에게 적립금 차감을 구성하시기 바랍니다.

콜백 URL 에는 아래의 값들이 제공됩니다.

이 값들은 개발자 서버로 호출 시 실제 값으로 변환됩니다.
콜백 URL 입력 시 반드시 대괄호까지 입력하시기 바랍니다.
아래의 사용예를 참고해주시기 바랍니다.

[USE_ID] : 결제 Unique 키값. 중복 차감 방지 및 환불 시 적립금 재 지급시 사용.
[PRICE] : 상품 금액
[USER_DATA] : 회원 정의 데이터

ex) http://test.co.rk/test.asp?UID=[USE_ID]&P=[PRICE]&UD=[USER_DATA]

구매 처리 결과값
개발자 서버에서 구매 처리가 끝난 후 JSON 타입으로 "result"와 "money"를 리턴해주시면 됩니다.
성공 - {"result":"1", "money":1000}
실패 - {"result":"0"}
result값은 1일때만, 정상 처리 되면, 구매가 실패 했을 시에는 0으로 내려주시면 됩니다.
money는 화면에 보여주는 사용자 금액으로 구매 처리후 남은 잔액을 내려주시면 됩니다. 해당 금액은 보여주는 용도로만 사용되며, 구매처리시 따로 체크를 하지는 않습니다.

"3. 구매 STEP 1"은 임시 구매에 해당하고, 실제 구매 처리는 개발자 서버의 구매 처리가 완료 된 후 "7. 구매 STEP 2"에서 진행이 됩니다.
개발자 서버의 금액 차감은 "3. 구매 STEP 1"에서 1차적으로 이루어지지만, "7. 구매 STEP 2"에서 성공처리 되지 않으면, 차감된 금액이 복구 됩니다.

❈ 적립금 중복 차감 방지를 위한 처리
1. 콜백 중복 호출 시, 적립금 중복 차감을 방지하기 위해, [USE_ID]를 기준으로 중복 차감을 막아주시기 바랍니다.
. 환불 프로세스 - TYPE A
* 사용 내역 관리를 개발사에서 직접 할 경우에 해당하는 결제 프로세스 입니다.

* 다음 이미지는 환불의 두가지 형태를 표현한 환불 프로세스 입니다.
1,2,3,4,5로 처리되는 환불 프로세스와 A,B,C로 이어지는 환불 프로세스 두가지입니다.



1. ~ 2. 매체사 App or 서버에서 환불시도 // 환불 API 호출
사용자 또는 개발사 서버에서 미탭스 플러스 쪽으로 환불을 시도 하는 경우 호출되는 API로 처리 결과는 JSON으로 리턴됩니다..
* 반드시 미탭스 서버의 환불 처리가 성공이 된 후에 개발사 서버에서 환불 처리를 하세요.

- URL
http://www.appang.kr/STORE/lock/StoreRefundProc.asp

- 파라메터 (*=필수항목)
aidkey * 앱 KEY
aidpwd * 앱 스토어 KEY
use_id * [USE_ID] - 결제 Unique 키값
ud * [USER_DATA] - 회원 정의 데이터

- 결과
result 1 : 환불 성공
그외 실패.
B. REFUND CALL BACK URL 호출
환불 URL은 NAS STORE 서버에서 개발자 서버로 호출하는 URL로 관리자가 직접 환불을 시도 하는 경우에 호출됩니다.
판매 내역을 관리하는 페이지에서 환불 요청시에도 호출됩니다.
개발사의 환불 처리 여부와 상관없이 미탭스 플러스의 환불이 우선시 됩니다.

[USE_ID] : 결제 Unique 키값. 상세 데이터 호출 및 환불 시 사용.
[USE_STATUS] : 2-구매, 3-환불
[REASON] : 환불 사유

http://test.co.rk/test.asp?UID=[USE_ID]&US=[USE_STATUS]&r=[REASON]

개발자 서버에서 환불 처리가 끝난 후 JSON 타입으로 result : 1을 반환해주시면 됩니다.
개발자 서버의 환불 처리 여부와 상관없이 미탭스 플러스 측은 환불 처리가 진행됩니다.
미탭스 플러스측의 환불이 처리되면, 차감된 보유 금액이 복구 됩니다.

❈ 적립금 중복 지급 방지를 위한 처리
1. 콜백 중복 호출 시, 적립금 중복 지급을 방지하기 위해, [USE_ID]를 기준으로 중복 지급을 막아주시기 바랍니다.
. 환불 프로세스 - TYPE B
* 사용 내역 관리를 NAS STORE 서버에서 할 경우에 해당하는 결제 프로세스 입니다.

* 다음 이미지는 환불의 두가지 형태를 표현한 환불 프로세스 입니다.



3. REFUND CALL BACK URL 호출 / 4. 매체사 환불 처리
환불 URL은 NAS STORE 서버에서 개발자 서버로 호출하는 URL로 사용자가 직접 환불하거나 관리자가 직접 환불을 시도 하는 경우에 호출됩니다.
개발사의 환불 처리 여부와 상관없이 미탭스 플러스의 환불이 우선시 됩니다.

[USE_ID] : 결제 Unique 키값. 중복 차감 방지 및 환불 시 적립금 재 지급시 사용.
[PRICE] : 상품 금액
[USER_DATA] : 회원 정의 데이터

ex) http://test.co.rk/test.asp?UID=[USE_ID]&P=[PRICE]&UD=[USER_DATA]

개발자 서버에서 환불 처리가 끝난 후 JSON 타입으로 result : 1을 반환해주시면 됩니다.
개발자 서버의 환불 처리 여부와 상관없이 미탭스 플러스 측은 환불 처리가 진행됩니다.
미탭스 플러스측의 환불이 처리되면, 차감된 보유 금액이 복구 됩니다.

❈ 적립금 중복 지급 방지를 위한 처리
1. 콜백 중복 호출 시, 적립금 중복 지급을 방지하기 위해, [USE_ID]를 기준으로 중복 지급을 막아주시기 바랍니다.
. 담당자 연락처
미탭스 플러스 개발팀 문한국
Email : hankook@metaps-plus.com