IAP Game Unreal Developer Guide - ONE-store/inapp-sdk GitHub Wiki

< 참고 >

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

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

해당 내용은 Unreal을 사용하는 안드로이드 앱에서 IAP SDK 적용을 돕기 위한 설명서이다. 이를 위해 OnestoreIapHelper 클래스(이하 OIAPhelper)를 제공한다.

1. OIAPhelper 소개

OIAPhelper는 IAP SDK 내 결제 관련 메서드를 호출하고, 응답 결과를 native 레벨로 보내는 역할을 하는 샘플 가이드 코드이다. OIAPhelper내에 정의된 native 메서드를 통해 응답 결과가 전달되기 때문에, OIAPhelper 내에 정의된 native 메서드들은 엔진(혹은 그 외 native 레벨)단에 반드시 구현 해야 한다.

Folder	File Name	Description
UE4/src	OnestoreIapHelper.java	IAP SDK 결제 API와 연동하기 위한 샘플 가이드 코드 호출 결과는 native 메서드를 통해 전달

2. OIAPhelper 적용

IAP SDK(.jar)에서 제공하는 API를 사용하기 위해 OIAPhelper를 엔진과 연동시켜야 한다.

1)최신 IAP SDK(.jar)를 작업 프로젝트 libs 폴더에 복사

2)OnestoreIapHelper.java 파일을 아래 엔진 폴더에 복사 (GameActivity.java가 존재하는 폴더)

\Engine\Build\Android\Java\src\com\epicgames\ue4\

3)GameActivity.java 수정

import 선언

import com.epicgames.ue4.OnestoreIapHelper;

OIAPhelper 관련 메서드 추가

  // Onestore manager objects
 private OnestoreIapHelper mOnestoreIapHelper = null;
 
 // Onestore In-App-Purchase functionality
 public void AndroidThunkJava_OnestoreIapSetupService(boolean isDebugMode) {
     Log.debug("[JAVA] - AndroidThunkJava_OnestoreIapSetupService. DebugMode : " + isDebugMode);

     if(mOnestoreIapHelper == null){
         mOnestoreIapHelper = new OnestoreIapHelper(this, isDebugMode);
     }
 }
 
 public void AndroidThunkJava_OnestoreIapRequestPurchase(final String appId, final String pId, final String pName, final String tId, final String bpInfo)   {
     if (mOnestoreIapHelper == null) {
        Log.debug("[JAVA] - OneStoreIapHelper is invalid");
             return;
     }
     mOnestoreIapHelper.requestPurchase(appId, pId, pName, tId, bpInfo);
 }
 
 public void AndroidThunkJava_OnestoreIapReceiptVerify(final String appId, final String txId, final String receiptSignData)
 {
     if (mOnestoreIapHelper == null) {
         Log.debug("[JAVA] - OneStoreIapHelper is invalid");
         return;
     }       
     mOnestoreIapHelper.doReceiptVerification(appId, txId, receiptSignData);
 }

public void AndroidThunkJava_OnestoreIapCmdPurchaseHistory(final String appId, final String pId)
{
     if (mOnestoreIapHelper == null) {
        Log.debug("[JAVA] - OneStoreIapHelper is invalid");
             return;
      }
      mOnestoreIapHelper.doCmdPurchaseHistory(appId, pId);
 }
 
 public void AndroidThunkJava_OnestoreIapCmdProductInfo(final String appId)
 {
     if (mOnestoreIapHelper == null) {
         Log.debug("[JAVA] - OneStoreIapHelper is invalid");
         return;
     }
     mOnestoreIapHelper.doCmdProductInfo(appId);
 }
 
 public void AndroidThunkJava_OnestoreIapCmdCheckPurchasability(final String appId, final String pId)
 {
     if (mOnestoreIapHelper == null) {
         Log.debug("[JAVA] - OneStoreIapHelper is invalid");
         return;
     }
     mOnestoreIapHelper.doCmdCheckPurchasability(appId, pId);
 }
 
 public void AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription(final String appId, final String pId)
 {
     if (mOnestoreIapHelper == null) {
         Log.debug("[JAVA] - OneStoreIapHelper is invalid");
         return;
     }       
     mOnestoreIapHelper.doCmdChangeProduct_withDrawSubscription(appId, pId);
 }
 
 public void AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints(final String appId, final String pId)
 {
     if (mOnestoreIapHelper == null) {
         Log.debug("[JAVA] - OneStoreIapHelper is invalid");
         return;
     }
     mOnestoreIapHelper.doCmdChangeProduct_descentPoints(appId, pId);
 }
 
 public void AndroidThunkJava_OnestoreIapCmdPurchaseHistory_bg(final String appId, final String pId)
 {
     if (mOnestoreIapHelper == null) {
         Log.debug("[JAVA] - OneStoreIapHelper is invalid");
         return;
     }
     mOnestoreIapHelper.doCmdPurchaseHistory_bg(appId, pId);
 }
 
public void AndroidThunkJava_OnestoreIapCmdProductInfo_bg(final String appId)
 {
     if (mOnestoreIapHelper == null) {
                Log.debug("[JAVA] - OneStoreIapHelper is invalid");
         return;
     }
      mOnestoreIapHelper.doCmdProductInfo_bg(appId);
}

 public void AndroidThunkJava_OnestoreIapCmdCheckPurchasability_bg(final String appId, final String pId)
 {
     if (mOnestoreIapHelper == null) {
         Log.debug("[JAVA] - OneStoreIapHelper is invalid");
         return;
     }
     mOnestoreIapHelper.doCmdCheckPurchasability_bg(appId, pId);
 }
 
 public void AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription_bg(final String appId, final String pId)
 {
     if (mOnestoreIapHelper == null) {
         Log.debug("[JAVA] - OneStoreIapHelper is invalid");
         return;
     }
     mOnestoreIapHelper.doCmdChangeProduct_withDrawSubscription_bg(appId, pId);
 }
 
 public void AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints_bg(final String appId, final String pId)
 {
     if (mOnestoreIapHelper == null) {
         Log.debug("[JAVA] - OneStoreIapHelper is invalid");
         return;
     }
}

4)AndroidJNI.h 및 Android.cpp 수정 Native 영역에서 Java 영역(GameActivity.java 클래스)에 정의된 메서드에 접근하기 위해 AndroidJNI.h 파일 및 AndroidJNI.cpp 파일을 수정해야 한다. 해당 파일은 아래 경로에 위치한다. (UE4 4.12 기준)

\Engine\Source\Runtime\Launch\Private\Android\AndroidJNI.cpp \Engine\Source\Runtime\Launch\Public\Android\AndroidJNI.h

< AndroidJNI.h >

  class FJavaWrapper{
   public:
   ... 
   // In app purchase functionality for Onestore
   static jmethodID AndroidThunkJava_OnestoreIapSetupService;
   static jmethodID AndroidThunkJava_OnestoreIapRequestPurchase;
   static jmethodID AndroidThunkJava_OnestoreIapReceiptVerify;
   
   static jmethodID AndroidThunkJava_OnestoreIapCmdPurchaseHistory;
   static jmethodID AndroidThunkJava_OnestoreIapCmdProductInfo;
   static jmethodID AndroidThunkJava_OnestoreIapCmdCheckPurchasability;
   static jmethodID AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription;
   static jmethodID AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints;

   static jmethodID AndroidThunkJava_OnestoreIapCmdPurchaseHistory_bg;
   static jmethodID AndroidThunkJava_OnestoreIapCmdProductInfo_bg;
   static jmethodID AndroidThunkJava_OnestoreIapCmdCheckPurchasability_bg;
   static jmethodID AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription_bg;
   static jmethodID AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints_bg;
   ...

< Android.cpp >

//Declare all the static members of the class defs 

...

// In app purchase functionality for Onestore
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapSetupService;
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapRequestPurchase;
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapReceiptVerify;

jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapCmdPurchaseHistory;
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapCmdProductInfo;
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapCmdCheckPurchasability;
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription;
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints;

jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapCmdPurchaseHistory_bg;
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapCmdProductInfo_bg;
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapCmdCheckPurchasability_bg;
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription_bg;
jmethodID FJavaWrapper::AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints_bg;

void FJavaWrapper::FindClassesAndMethods(JNIEnv* Env)
{

...

// Onestore IAP method id
    AndroidThunkJava_OnestoreIapSetupService = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapSetupService", "(Z)V", bIsOptional);
    AndroidThunkJava_OnestoreIapRequestPurchase = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapRequestPurchase", "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V", bIsOptional);
    AndroidThunkJava_OnestoreIapReceiptVerify = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapReceiptVerify", "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V",bIsOptional);

    AndroidThunkJava_OnestoreIapCmdPurchaseHistory = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapCmdPurchaseHistory", "(Ljava/lang/String;Ljava/lang/String;)V",bIsOptional);
    AndroidThunkJava_OnestoreIapCmdProductInfo = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapCmdProductInfo", "(Ljava/lang/String;)V",bIsOptional);
    AndroidThunkJava_OnestoreIapCmdCheckPurchasability = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapCmdCheckPurchasability", "(Ljava/lang/String;Ljava/lang/String;)V",bIsOptional);
    AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription", "(Ljava/lang/String;Ljava/lang/String;)V",bIsOptional);
    AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints", "(Ljava/lang/String;Ljava/lang/String;)V",bIsOptional);

    AndroidThunkJava_OnestoreIapCmdPurchaseHistory_bg = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapCmdPurchaseHistory_bg", "(Ljava/lang/String;Ljava/lang/String;)V",bIsOptional);
    AndroidThunkJava_OnestoreIapCmdProductInfo_bg = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapCmdProductInfo_bg", "(Ljava/lang/String;)V",bIsOptional);
    AndroidThunkJava_OnestoreIapCmdCheckPurchasability_bg = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapCmdCheckPurchasability_bg", "(Ljava/lang/String;Ljava/lang/String;)V",bIsOptional);
    AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription_bg = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription_bg", "(Ljava/lang/String;Ljava/lang/String;)V",bIsOptional);
    AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints_bg = FindMethod(Env, GameActivityClassID, "AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints_bg", "(Ljava/lang/String;Ljava/lang/String;)V",bIsOptional);

상기 작업을 통해 Native 영역에서는 JavaWrapper 클래스의 멤버함수인 FindClassesAndMethods 함수를 통해 GameActivity에 작성해놓은 메서드에 접근할 수 있으므로 결제가 필요한 시점에 호출하여 사용하면 된다.

5)native 메서드 구현 결제 응답에 대한 콜백은 OnestoreIapHelper.java내에 정의된 native 메서드로 전달되기 때문에 native 영역에 해당 메서드들을 구현해야 한다. 보통 결제 응답에 따른 전자영수증 정보의 검증(서버 to 서버)과 이에 따른 아이템 지급등의 로직을 구현하게 된다.

6)안드로이드 세팅 IAP SDK와 정상적으로 연동하기 위해서는 반드시 안드로이드 Manifest 설정을 해주어야 한다. 언리얼 엔진의 프로젝트 설정 메뉴에서 아래와 같이 설정할 수 있다.

enter image description here

추가 정보는 아래와 같이 3가지이다. Meta-data 설정은 'Extra Settings for section..' 항목에 추가하고, Permission 설정은 'Extra Permissions..' 항목에 추가한다.

Meta-data

<meta-data 
    android:name="iap:api_version"
    android:value="4" />

Permission

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

안드로이드 인앱결제 서비스의 manifest 파일의 예

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.skplanet.iapexample"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-sdk
        android:minSdkVersion="14"
        android:targetSdkVersion="23" />

<uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.RECEIVE_SMS" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    
    <application
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        
        <meta-data
            android:name="iap:api_version"
            android:value="4" />
        
        <activity
            android:name=".MainActivity"
            android:label="@string/app_name" 
            android:theme="@android:style/Theme.Holo.Light">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

3. 인앱결제 구현

초기화

// Onestore manager objects
private OnestoreIapHelper mOnestoreIapHelper = null;
    
// Onestore In-App-Purchase functionality
public void AndroidThunkJava_OnestoreIapSetupService(boolean isDebugMode) {
        Log.debug("[JAVA] - AndroidThunkJava_OnestoreIapSetupService. DebugMode : " + isDebugMode);

        if(mOnestoreIapHelper == null){
            mOnestoreIapHelper = new OnestoreIapHelper(this, isDebugMode);
        }
}

결제(Payment) 처리

public void AndroidThunkJava_OnestoreIapRequestPurchase(final String appId, final String pId, final String pName, final String tId, final String bpInfo)	{
		if (mOnestoreIapHelper == null) {
			Log.debug("[JAVA] - OneStoreIapHelper is invalid");
            return;
		}

        mOnestoreIapHelper.requestPurchase(appId, pId, pName, tId, bpInfo);
}

// Callback
public native void nativeOnPaymentComplete(String resultString);
public native void nativeOnPaymentError(String reqId, String errCode, String errMsg);

쿼리(Query) 처리

public void AndroidThunkJava_OnestoreIapCmdPurchaseHistory(final String appId, final String pId)
{
		if (mOnestoreIapHelper == null) {
			Log.debug("[JAVA] - OneStoreIapHelper is invalid");
            return;
		}
        
        mOnestoreIapHelper.doCmdPurchaseHistory(appId, pId);
        //mOnestoreIapHelper.doCmdPurchaseHistory_bg(appId, pId);
}
    
public void AndroidThunkJava_OnestoreIapCmdProductInfo(final String appId)
{
        if (mOnestoreIapHelper == null) {
            Log.debug("[JAVA] - OneStoreIapHelper is invalid");
            return;
        }
        
        mOnestoreIapHelper.doCmdProductInfo(appId);
        //mOnestoreIapHelper.doCmdProductInfo_bg(appId);
}
    
public void AndroidThunkJava_OnestoreIapCmdCheckPurchasability(final String appId, final String pId)
{ 
        if (mOnestoreIapHelper == null) {
            Log.debug("[JAVA] - OneStoreIapHelper is invalid");
            return;
        }
       
        mOnestoreIapHelper.doCmdCheckPurchasability(appId, pId);
        //mOnestoreIapHelper.doCmdCheckPurchasability_bg(appId, pId);
}
    
public void AndroidThunkJava_OnestoreIapCmdChangeProduct_withDrawSubscription(final String appId, final String pId)
    {
        if (mOnestoreIapHelper == null) {
            Log.debug("[JAVA] - OneStoreIapHelper is invalid");
            return;
        }
        
        mOnestoreIapHelper.doCmdChangeProduct_withDrawSubscription(appId, pId);
        //mOnestoreIapHelper.doCmdChangeProduct_withDrawSubscription_bg(appId, pId);
}
    
public void AndroidThunkJava_OnestoreIapCmdChangeProduct_descentPoints(final String appId, final String pId)
{      
        if (mOnestoreIapHelper == null) {
            Log.debug("[JAVA] - OneStoreIapHelper is invalid");
            return;
        }
        
        mOnestoreIapHelper.doCmdChangeProduct_descentPoints(appId, pId);
        //mOnestoreIapHelper.doCmdChangeProduct_descentPoints_bg(appId, pId);
}

// Callback
public native void nativeOnCommandComplete(String resultString);
public native void nativeOnCommandError(String reqId, String errCode, String errMsg);

전자영수증검증 처리

결제 결과 영수증에 대한 검증 기능을 한다. 별도의 개발서버가 없을 경우에만 사용하길 권장한다. 가급적 개발서버에서 Server API를 통해 호출하는 것을 권장한다. (https://github.com/ONE-store/inapp-sdk/wiki/IAP-Reference-Server-API)

public void AndroidThunkJava_OnestoreIapReceiptVerify(final String appId, final String txId, final String receiptSignData)
{
        if (mOnestoreIapHelper == null) {
            Log.debug("[JAVA] - OneStoreIapHelper is invalid");
            return;
        }
        
        mOnestoreIapHelper.doReceiptVerification(appId, txId, receiptSignData);
}

// Callback
public native void nativeOnVerifyReceiptComplete(String resultString);
public native void nativeOnVerifyReceiptError(String errCode);