Unity에서 ALC SDK V2 사용하기

개요

원스토어 앱 라이선스 검증 플러그인은 Unity 환경에서 손쉽게 유료 앱 구매 검증을 적용할 수 있도록 지원하는 플러그인입니다.

이 플러그인을 활용하면 앱의 무단 사용을 방지하고, 정품 사용자만 이용할 수 있도록 보호할 수 있습니다.

본 가이드에서는 다음 내용을 다룹니다

프로젝트에 플러그인을 설정하는 방법
플러그인을 활용하여 원스토어 앱 라이선스 검증 기능을 적용하는 방법
라이선스 검증 라이브러리의 주요 기능 구현 방법

이 가이드를 참고하여 Unity 환경에서 원스토어 라이선스 검증을 간편하게 적용하고, 앱 보안을 강화하세요.

개발 버전

Unity

2022.3.11f1

Java SDK (Java 11)

Purchase: v21.02.01

App License Checker: v2.2.1

앱 라이선스 검증 플러그인 설정

플러그인 다운로드 및 가져오기

GitHub의 Release 페이지에서 Unity 용 원스토어 인앱결제 플러그인 최신 버전을 다운로드합니다.
Unity 메뉴 바에서 Assets > Import Package > Custom Package를 클릭합니다.
다운로드한 위치를 찾아 .unitypackage 파일을 선택합니다.
Import Unity Package 대화상자에서 모든 에셋을 선택한 상태로 두고 Import를 클릭합니다.

패키지를 가져오면 폴더가 추가됩니다. 이 폴더에 원스토어 결제 라이브러리가 포함되어 있습니다.

Assets/OneStoreCorpPlugins
- /Common
- /Authentication
- /Purchase
- /AppLicenseChecker

EDM4U(External Dependency Manager for Unity)가 필수로 같이 배포됩니다. 만약, 이미 사용하고 있다면 Import Package 단계에서 ExternalDependencyManager를 체크해지하고 적용하면 됩니다.

외부 종속성 포함

프로젝트에 레파지토리 및 종속성이 포함되도록 하려면 다음 단계를 따릅니다.

Project Settings > Player > Publishing Settings > Build

아래의 두 가지를 체크합니다.

Custom Main Manifest
Custom Main Gradle Template

Assets > External Dependency Manager > Android Resolver > Force Resolve 를 선택합니다.

mainTemplete.gradle 파일에 아래와 같이 적용되는 것을 확인할 수 있습니다.

In-app Purchase 종속성은 다음에 나열되어 있습니다. Assets/OneStoreCorpPlugins/Purchase/Editor/PurchaseDependencies.xml
App License Checker 종속성은 다음에 나열되어 있습니다. Assets/OneStoreCorpPlugins/AppLicenseChecker/Editor/AppLicenseCheckerDependencies.xml

<queries> 설정

AndroidManifest.xml 파일에 <queries>를 설정 해야합니다. 자세한 내용은 공지사항을 참조하세요.

<queries> 태그를 설정하지 않으면 SDK에서 원스토어 서비스를 찾을 수 없습니다.

<manifest>
    <!-- 
        if your binary use ONE store's In-app SDK,
        Please make sure to declare the following query on Androidmanifest.xml. 
        Refer to the notice for more information.
        https://dev.onestore.net/devpoc/support/news/noticeView.omp?noticeId=32968
     -->
    <queries>
        <intent>
            <action android:name="com.onestore.extern.licensing.LicensingService.ACTION" /> 
        </intent>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="onestore" />
        </intent>
    </queries>
    ...
    <application>
        ...
    </application>
</manifest>

스토어 선택을 위한 개발자 옵션 설정

v2.2.0 업데이트 - 글로벌 스토어 선택 기능 추가

ALC SDK 2.2.0 부터 아래와 같이 onestore:dev_option의 android:value 값을 설정하면, SDK와 연동되는 스토어 앱을 지정 할 수 있습니다.

<manifest>
    <application>
        <meta-data android:name="onestore:dev_option" android:value="onestore_01" />
    </application>
</manifest>

값 (android:value)

적용 대상 국가

onestore_00

대한민국 (South Korea) (기본값)

onestore_01

싱가포르, 타이완 (Singapore, Taiwan)

onestore_02

미국 – Digital Turbine (United States)

주의: 배포 버전의 바이너리에서는 이 옵션을 반드시 제거해주세요.

ACL 라이브러리 적용하기

로그 레벨 설정

개발 단계에서 로그 레벨을 설정하여 SDK의 데이터의 흐름을 좀 더 자세히 노출할 수 있습니다. android.util.Log에 정의된 값을 기반으로 동작합니다.

using OneStore.Common;
/// <summary>
/// Warning! This code must be deleted during release build as it may be vulnerable to security.
/// Use <seealso cref="OneStoreLogger.SetLogLevel(int)"/> only for development.
/// </summary>
OneStoreLogger.SetLogLevel(2);

상수

값

VERBOSE

DEBUG

INFO (default)

WARN

ERROR

배포 빌드 버전에서는 보안에 취약할 수 있으니 이 옵션을 삭제해야 합니다.

라이선스 키 확인 및 적용하기

앱의 라이선스를 검증하려면 원스토어 개발자 센터에서 제공하는 라이선스 키가 필요합니다.

이 라이선스 키를 확인하고 복사한 후, ALC (Application License Checker) 객체를 생성하여 앱에 적용할 수 있습니다.

라이선스 키 확인 및 복사 방법

원스토어 개발자 센터 접속하여 로그인합니다.
앱 상품 현황 페이지 이동
라이선스 관리 메뉴 진입하여 라이선스 키 복사

AppLicenseChecker 초기화

앱에서 원스토어 라이선스 검증을 수행하려면 Initialize() 함수를 호출하여 기본적인 설정을 완료해야 합니다. 라이선스 검증 결과는 ILicenseCheckCallback 인터페이스를 통해 이벤트로 전달됩니다.

다음 작업은 원스토어 서비스 연결 및 앱 라이선스 검증 요청을 위한 필수 선행 작업입니다.

using OneStore.Alc;

// Implement ILicenseCheckCallback to handle license verification results
class YourCallback : ILicenseCheckCallback
{
    // Called when the license is valid
    public void OnGranted(string license, string signature) 
    {
        // License verification successful
    }

    // Called when the license is denied
    public void OnDenied() 
    {
        // License verification failed
    }

    // Called when an error occurs during license verification
    public void OnError(int code, string message) 
    {
        // Handle error with code and message
    }
}

// Create an instance of OneStoreAppLicenseCheckerImpl with your license key
OneStoreAppLicenseCheckerImpl _appLicenseCheckerImpl = new OneStoreAppLicenseCheckerImpl("your_license_key");

// Initialize the license checker with the implemented callback
_appLicenseCheckerImpl.Initialize(new YourCallback());

라이선스 검증 요청하기

앱에서 라이선스 검증을 요청하면, 원스토어 서버와 통신하여 사용자의 구매 라이선스를 확인합니다. 그러나 일시적인 네트워크 문제, 비행기 모드 등의 이유로 서버에 접근할 수 없는 경우 앱 실행이 차단될 수 있습니다.

이를 방지하기 위해, 일반적으로 캐시 정책을 사용하여 로컬에 저장된 라이선스를 기반으로 앱을 실행할 수 있도록 보장합니다.

만약 캐시된 라이선스를 사용하지 않고 실시간 검증을 원할 경우, strictQueryLicense API를 사용하면 항상 원스토어 서버에서 최신 라이선스를 조회할 수 있습니다.

QueryLicense API (Cached API) 호출

캐시 정책을 적용하여 동작하는 라이선스 검증 API입니다.

기본적으로 원스토어 서버와 통신하여 사용자의 구매 라이선스를 확인합니다.
그러나 네트워크 장애, 비행기 모드 등으로 서버에 접근할 수 없는 경우, 로컬에 저장된 라이선스를 이용하여 앱 실행을 보장합니다.
로컬 캐시에 저장된 라이선스는 유효 기간 내에서만 사용 가능하며, 만료되면 서버와 다시 통신해야 합니다.

이 방식은 사용자 경험을 개선하고, 일시적인 네트워크 문제로 인해 앱 실행이 차단되는 것을 방지하는 데 유용합니다.

_appLicenseCheckerImpl.QueryLicense();

StrictQueryLicense API (Non-Cached API) 호출

StrictQueryLicense API는 캐시된 라이선스를 사용하지 않고, 항상 원스토어 서버에서 최신 라이선스를 조회하는 방식입니다.

캐시를 사용하지 않기 때문에, 항상 최신 라이선스 정보를 기반으로 검증이 이루어집니다.
그러나 네트워크 장애, 비행기 모드 등의 상황에서는 원스토어 서버에 접근할 수 없기 때문에, 라이선스 검증이 실패하면 앱을 사용할 수 없습니다.
보안이 중요한 경우 유용할 수 있지만, 네트워크 문제로 인해 앱 사용이 제한될 수 있으므로 사용 목적에 맞게 신중히 선택해야 합니다.

_appLicenseCheckerImpl.StrictQueryLicense();

연결 해제

원스토어 서비스와의 불필요한 연결을 방지하고 리소스를 적절히 해제하기 위해, 더 이상 라이선스 검증이 필요하지 않을 경우 AppLicenseChecker의 Destroy() 메서드를 호출하여 연결을 해제하는 것을 권장합니다.

이렇게 하면 메모리 누수를 방지하고, 불필요한 서비스 호출을 차단하여 앱의 성능을 최적화할 수 있습니다.

_appLicenseCheckerImpl.Destroy();

설치 마켓 확인하기

StoreEnvironment.GetStoreType() API는 SDK가 탑재된 애플리케이션이 원스토어를 통해 설치되었는지를 판단하는 기능을 제공합니다.

Store Type 정의

해당 API는 StoreType을 반환하며, 아래 네 가지 값 중 하나를 가집니다.

StoreType

value

description

StoreType.UNKNOWN

앱 설치 스토어 정보를 알 수 없음 (APK 직접 설치, 출처 불명 등)

StoreType.ONESTORE

ONE Store에서 설치됨 (또는 개발자 옵션이 활성화된 경우)

StoreType.VENDING

Google Play Store에서 설치됨

StoreType.ETC

기타 스토어에서 설치됨

API 사용 방법

해당 API는 StoreEnvironment.GetStoreType()을 호출하여 사용할 수 있습니다.

using OneStore.Common;

public void DetectStoreEnvironment()
{
    var storeType = StoreEnvironment.GetStoreType();
    switch (storeType) 
    {
        case StoreType.ONESTORE:
            UnityEngine.Debug.Log("ONE Store");
            break;
        case StoreType.VENDING:
            UnityEngine.Debug.Log("Google Play Store");
            break;
        case StoreType.ETC: 
            UnityEngine.Debug.Log("Other stores");
            break;
        // StoreType.UNKNOWN
        default:
            UnityEngine.Debug.Log("Unknown store");
            break;
    }
}

스토어 판단 기준

이 API는 세 가지 방법을 통해 설치된 스토어를 판별합니다.

원스토어 마켓 서명을 통해 배포된 경우
1. 원스토어의 마켓 서명을 통한 배포 여부를 확인하여, 원스토어에서 설치된 앱인지 확인합니다.
Installer Package Name을 기반으로 판별
1. 원스토어의 마켓 서명을 통해 배포되지 않은 경우, PackageManager.getInstallerPackageName() API를 이용하여 앱 설치 시 사용된 스토어 정보를 확인합니다.
개발자 옵션(onestore:dev_option)이 활성화된 경우
1. onestore:dev_option 이 설정 되어있으면 무조건 StoreType.ONESTORE로 응답합니다.

응답 코드

다음 표는 원스토어 ALC 라이브러리에서 앱으로 전달되는 에러 응답 코드 및 메시지입니다.

라이브러리를 사용하는 앱에서는 각 응답 코드에 대해 적절한 처리를 수행해야 합니다.

Response Code

Value

Description(KR)

Description(EN)

How to handle

RESULT_OK

성공

Success

ERROR_CLIENT_NOT_ENABLED

1010

원스토어에 연결할 수 없습니다. 원스토어 앱 실행이 필요합니다.

Unable to connect to the store. ONE store app execution is required.

ERROR_SERVICE_UNAVAILABLE

2000

서비스를 이용할 수 없는 상태입니다.

The service is unavailable.

원스토어에 문의해주세요.

ERROR_DATA_PARSING

2001

파라메터가 유효하지 않습니다.

Parameter is invalid.

원스토어에 문의해주세요.

ERROR_SIGNATURE_VERIFICATION

2002

라이선스 키가 맞지 않거나 구매 내역이 없는 유저 입니다.

The license key is not matched, or the user does not have a purchase history.

원스토어 개발자 센터에서 라이선스 키를 확인해주세요.

ERROR_SERVICE_TIMEOUT

2100

서비스 응답이 없습니다.

There is no response.

네트워크 상태를 체크해주세요.

ERROR_USER_LOGIN_CANCELD

2101

사용자가 로그인을 취소하였습니다.

User canceled login.

원스토어 로그인을 해주세요.

ERROR_INSTALL_USER_CANCELED

2103

원스토어 서비스 설치를 취소하였습니다.

ONE store install has been canceled. Do you want to ONE store installation?

원스토어를 설치해주세요.

ERROR_NOT_FOREGROUND

2104

백그라운드 서비스에서는 진행할 수 없습니다.

Can not run the context is not instance of Activity.

RESULT_UNKNOWN

-1

알 수 없는 오류가 발생하였습니다.

An unknown error occurred.

원스토어에 문의해주세요.

RESULT_USER_CANCELED

사용자가 로그인을 취소하였습니다.

User canceled login.

원스토어 로그인을 해주세요.

RESULT_SERVICE_UNAVAILABLE

단말 또는 서버 네트워크 오류가 발생하였습니다.

A device or server network error has occurred.

네트워크 상태를 체크해주세요.

RESULT_ALC_UNAVAILABLE

ALC api 버전 정보가 낮습니다. 해당 라이브러리를 업데이트 해주세요.

The ALC api has the lower version. Please update the corresponding library.

ALC 라이브러리를 최신버전으로 업데이트 해주세요.

RESULT_DEVELOPER_ERROR

파라메터가 유효하지 않습니다.

The parameter is invalid.

원스토어에 문의해주세요.

RESULT_ERROR

정의되지 않은 기타 오류가 발생하였습니다.

An unknown error occurred.

원스토어에 문의해주세요.

Last updated 1 month ago