Unity 빌링

Unity에서 HYBE Game Platform Service(이하, HGPS) 결제 서비스 연동을 위한 Unity SDK 사용법에 대해서 설명합니다.

요구사항

Unity용 Platform SDK를 사용하기 위한 요구 사항은 아래와 같습니다.

• 최소 사양 : 2021.3.1f

• OS : Android, iOS, Windows

• Store : PlayStore, 예정(Apple AppStore, Steam, Google PC, IM Launcher)

Apple AppStore, Steam 등 추가 결제 환경이 추가될 예정으로 일부 API는 변동 될 수 있습니다.

연동 준비

SDK 설치

결제 SDK 패키지는 Platform SDK에 통합되어 배포됩니다. Unity에서 Platform SDK를 사용하기 위한 프로젝트를 구성하는 방법은 다음과 같습니다.

1. 지정된 메뉴에서 SDK를 다운로드 합니다.

2. Unity에서 Assets > Import Package > Custom Package... 메뉴를 차례로 선택한 후 HyPlatformPlugin.unitypackage 파일을 선택합니다.

3. Import 팝업에서 [import] 버튼을 클릭하여 SDK를 현재 프로젝트에 설치합니다.

폴더 설명

Platform SDK 에 포함된 구성과 동일합니다. 아래 폴더에 결제 모듈 지원 파일이 추가 됩니다.

폴더 명	용도
HyPlatform	Plugins 폴더 하위에 Android, iOS, Windows 별로 파일이 위치합니다.

Android 환경 설정

안드로이드 결제 환경

• 결제 라이브러리 V6

• target API Level 34

커스텀 Gradle 추가

1. Project Setting > Publishing Settings > Build > Custom Main Gradle Template 체크

   1. Assets\Plugins\Android\mainTemplate.gradle 파일 생성됨

2. 결제 라이브러리 gradle 설정

dependencies {
    --- 중간 생략 ---
// Android Resolver Dependencies End
    implementation "com.android.billingclient:billing:6.0.1"
    implementation "com.android.billingclient:billing-ktx:6.0.1"
    implementation 'com.google.code.gson:gson:2.10.1'
**DEPS**}

안드로이드 속성 추가

1. Project Setting > Publishing Settings > Build > Custom Gradle Properties Template 체크

   1. Assets\Plugins\Android\gradleTemplate.properties 파일 생성됨

2. android 속성 추가

android.useAndroidX = true
android.enableJetifier = true

Google Play Console에서 인앱 상품 등록이 가능한 상태이어야 합니다.

PlayStore 상품 구매 환경 확인

Google Play Console > 등록된 앱 > 제품 > 인앱 상품 등록에서 확인할 수 있습니다.

[새 APK 업로드] 버튼이 보이는 경우 결제 라이브러리를 포함한 빌드를 업로드 해야합니다.

PlayStore 상품 구매 환경 만들기

안드로이드 결제 라이브러리가 포함된 APK/AAB를 PlayStore에 업로드하면 인앱 상품을 등록할 수 있습니다.

위의 안드로이드 가이드에 따라 결제 라이브러리 gradle 설정 및 속성 추가 후 빌드를 Play Store에 등록합니다.

iOS 결제 환경 설정

In-App Purchase 라이브러리 추가

• Xcode 설정

  • TARGETS > Unity-iPhone > Signing & Capabilities > Show Library(우상단 [+])

    • In-App Purchase 추가

Xcode 라이브러리에는 아래 3개의 라이브러리가 등록되어 있어야 합니다.

스팀 결제 환경 설정

플랫폼에 제공하는 별도의 설정은 필요하지 않습니다.

스팀에서 게임을 실행하는 경우 스팀 오버레이 결제 팝업을 통해서 결제를 진행합니다.

결제 전에 오버레이 기능이 활성화 되어 있는지 체크해야 합니다.

API 연동

StartPurchase 대리자 등록 (SDK 0.12.1 <= )

일부 결제 플랫폼에서는 지불을 시작하기 위한 함수를 게임 클라이언트(개발사)에서 직접 구현해줘야 합니다.

SDK에서는 단일한 인터페이스(BillingPlatform.StartPurchase)를 통해서 지불을 시작할 수 있도록 이러한 함수들을 대리자를 통해 등록받고 있습니다.

등록된 함수들은 BillingPlatform.StartPurchase 함수가 호출될 경우 실행됩니다.

플랫폼	함수 이름
Steam	BillingPlatform.RegisterSteamInitTxnHandler
GooglePC	BillingPlatform.RegisterGooglePCPurchaseHandler
Xsolla	BillingPlatform.RegisterXsollaPurchaseHandler

API Flow (Android, iOS)

1. 빌링 환경 구성

2. 결제 플랫폼 연결

3. 상품 준비

4. 구매

API 적용 순서 (Android, iOS)

1. IBillingAgent 클래스 작성

2. IBillingAgent 클래스 등록

3. 결제 플랫폼 연결

4. 구매할 상품 조회

   1. 상품 조회 결과 출력(상점)

5. 상품 구매

   1. 상품 예약

6. 상품 구매 이벤트 핸들러

   1. 영수증 검증

   2. 소비 처리

API Flow (Steam)

스팀 결제는 다른 결제 방식과 다른 Flow를 제공합니다.

BillingPlatform에 구매를 요청하지 않고, 게임서버에 구매를 요청해야 합니다.

API 적용 순서 (Steam)

1. IBillingAgent 클래스 작성

2. IBillingAgent 클래스 등록

3. 결제 플랫폼 연결

4. 게임 서버에 구매할 상품 조회

   1. 상품 조회 결과 출력(상점)

5. 게임 서버에 상품 구매 요청

   1. 상품 예약 후 결제 팝업

6. 상품 구매 이벤트 핸들러

   1. OnContinueSteamPurchase 작성

   2. 게임 서버에 상품 구매 완료 요청

API Flow (Google Play PC)

Google Play PC는 다른 결제 방식과 다른 Flow를 제공합니다.

• 결제 권한으로 Google 계정 로그인

• 외부 브라우저에서 상품 결제

상품 구입 확인 재시도 Flow

Google Play PC에서는 결제가 완료되었음을 유저 이벤트에 의존할 수 밖에 없기 때문에 (구글에서 결제 완료를 판단할 수 있는 별도의 이벤트를 제공하지 않음) 결제 처리가 지연될 경우에 대한 처리가 필요합니다.

1. 유저가 결제를 완료했음을 알리는 버튼을 클릭함

2. (Google 결제가 딜레이됨)

3. 아직 결제가 완료되지 않았으므로 백엔드 서버에서는 영수증 검증에 실패함

   3.1 일정 시간 대기후 자동으로 재시도 (상황에 따라 1회 이상 가능)

   3.2 유저에게 팝업을 노출하여 동의시 재시도

API Flow (XSOLLA)

엑솔라(XSOLLA) 다른 결제 방식과 다른 Flow를 제공합니다.

• SDK에 상품 정보 조회

• 게임서버에 결제 예약

  • 결제 URL 수신

• 외부 브라우저에서 상품 결제

API 적용 순서 (Google Play PC, Xsolla)

1. IBillingAgent 클래스 작성

2. IBillingAgent 클래스 등록

3. 결제 플랫폼 연결

   1. 웹뷰에 구글 로그인(Signin) 창이 팝업 됩니다. (Google Play PC의 경우)

4. BillingPlatform에 구매할 상품 조회

   1. 상품 조회 결과 출력(상점)

5. BillingPlatform에 상품 구매 요청

   1. 상품 결제 창이 외부 브라우저에 팝업 됩니다.

6. 인게임 결제 완료 확인 팝업

   1. 브라우저에서 결제 후 계속 진행 여부 선택

7. 상품 구매 이벤트 핸들러

   1. 게임 서버에 상품 구매 완료 요청

Google Play PC는 상품 정보 조회 시에 결제 권한을 가지는 구글 계정 로그인이 필요합니다.

그러므로, 상점 UX를 팝업하는 시점에 BillingPlatform 초기화(prepare)를 1회 수행해야합니다.

엑솔라 결제 완료 후 “게임으로 돌아가기” 기능을 제공합니다. ’게임으로 돌아가기’ 기능을 제공하기 위해서는 클라이언트에서 결제 페이지 오픈 후에 아래 메소드를 호출해야 합니다.

유니티 개발 환경에서 “게임으로 돌아가기” 이벤트를 수신하기 위해서는 아래 파일이 등록되어야 합니다.

HyAgent.zip 을 임의의 위치에 압축 해제하고 함께 제공되는 register.bat 파일을 관리자 모드에서 실행합니다.

API 연동 상세 정보

Billing 클래스

결제 지원으로 다음의 클래스가 추가되었습니다.

클래스	개발담당	설명
BillingPlatform	SDK	SDK 결제 기능을 제공
ProductManager	SDK	상품 상세 정보 조회 기능 제공
IBillingAgent	SDK	결제 과정에서 발생하는 이벤트를 정의한 인터페이스
ClientBillingAgent	개발사	게임 클라이언트에서 결제 이벤트 수신을 위해 구현해야 하는 클래스

IBillingAgent 인터페이스

IBillingAgent는 결제 프로세스에서 발생하는 이벤트를 정의한 인터페이스이다. 게임 클라이언트는 IBillingAgent 를 구현한 클래스를 제공 해야 한다.

public interface IBillingAgent
{
  void OnPurchasesUpdated(string boid, string resultJson);
  void OnUnconsumedPurchasesUpdated(string boid, string resultJson);
  void OnPurchasesCanceled();
  void OnPurchasesError(int code, string message);
#if UNITY_STANDALONE_WIN
  void OnContinueSteamPurchase(string boid);
#endif
}

• OnPurchasesUpdated : 상품 결제 시 호출되는 콜백

• OnPurchasesCanceled : 상품 결제 취소 시 호출되는 콜백

• OnPurchasesError : 상품 결제 오류 시 호출되는 콜백

• OnUnconsumedPurchasesUpdated : 소비 처리되지 않은 구매 발생 시 호출되는 콜백

• OnContinueSteamPurchase : 스팀 결제 창이 Close 되었을 때 호출되는 콜백

자세한 설명은 아래 상품 구매 이벤트 핸들러 구현에서 확인할 수 있습니다.

IBillingAgent 클래스 작성

플랫폼의 결제 진행 중 게임 클라이언트로 전달되는 결제 이벤트를 수신하기 위해서 IBillingAgent를 구현 해야 한다.

• 결제 플랫폼 연결

• 상품 조회

• 구매 요청

• 구매 이벤트 수신

  • 구매 성공

  • 구매 취소

  • 구매 에러

아래 샘플 코드를 참고하세요.

internal class ClientBillingAgent : IBillingAgent
{
    /// 결제 성공시 호출되는 콜백
    /// <param name="boid">상품 예약 boid</param>
    /// <param name="resultJson">구매 영수증 JSON</param>
    public override void OnPurchasesUpdated(string boid, string resultJson)
    {
        //1. 게임 서버에 구매 영수증을 제공하여 주문을 검증한다.
        게임서버영수증검증요청(resultJson);

        //2. 구매를 확정하여 소비처리를 진행한다.
        게임서버구매확정요청(productId, boid);
    }

    /// 소비처리 되지 않은 구매건 있는 경우 호출되는 콜백
    /// <param name="boid">상품 예약 boid</param>
    /// <param name="resultJson">구매 영수증 JSON</param>
    public override void OnPurchasesUpdated(string boid, string resultJson)
    {
        //1. 게임 서버에 구매 영수증을 제공하여 주문을 검증한다.
        게임서버영수증검증요청(resultJson);

        //2. 구매를 확정하여 소비처리를 진행한다.
        게임서버구매확정요청(productId, boid);
    }

    // 상품 구매 취소시 호출되는 콜백
    public override void OnPurchasesCanceled()
    {
        Debug.Log($"상품 구매가 취소 되었습니다.}");
    }

    // 상품 구매 과정에서 오류 발생시 호출되는 콜백
    public override void OnPurchasesError(int code, string message)
    {
        Debug.Log($"구매 도중 오류가 발생했습니다.\\nCode : {code}\\n{message}");
    }

    /// 지정된 상품을 구매한다.
    public bool StartPurchase(string productId)
    {
        //1. 구매 가능 상태인지 검사한다.
        if (BillingPlatform.Instance.CanPurchable() == false)
            return false;

        //2. 게임서버에게 구매할 상품을 예약한다.
        string boid = 게임서버상품예약요청(productId);

        //3. 상품 구매 프로세스를 시작한다.
        return BillingPlatform.Instance.StartPurchase(productId, boid);
    }

#if UNITY_STANDALONE_WIN
    public void OnContinueSteamPurchase(string boid)
    {
        Debug.Log($"스팀 결제팝업이 Close 되었습니다.}");
    }
#endif
}

IBillingAgent 클래스 등록

작성한 ClientBillingAgent는 결제 플랫폼에 Agent로 등록합니다.

PlatformSupervisor.Mount("prod").ContinueWithOnMainThread(task =>
{
    if (task.Result == true)
    {
					-- 중 략 --
        // 결제 기능을 제공하는 IBillingAgent를 설정한다.
        BillingPlatform.RegisterBillingAgent(new ClientBillingAgent());
    }
});

결제 절차

결제 플랫폼 연결

플랫폼 결제 환경을 준비 합니다.

BillingPlatform.PreInit()

public void PreInit(string playerId)

결제 환경을 구성한다.

접속한 Player ID 정보를 알 수 있는 시점에 호출해야 합니다. 주로 게임 서버 접속 후 호출합니다.

파라미터

• playerId Player ID

  • PlayerID는 소비처리 되지 않는 구매 조회시에 사용됩니다.

//1. 결제 환경 초기화
BillingPlatform.Instance.PreInit("my_play_id")

BillingPlatform.Prepare

public bool Prepare(Action<BillingResultCode> callback)

결제 환경 초기화 후에 호출합니다.

주로 판매할 상품에 대한 정보를 조회하기 전에 호출합니다. 중복 호출이 가능하며 결제 환경이 초기화되지 않은 경우 초기화를 수행합니다.

Google Play PC 환경인 경우 상품 조회 전에 반드시 호출해야 합니다.

결제권한을 요청하는 구글 로그인 창이 팝업 됩니다. 1회만 팝업되고 이후에는 캐싱된 토큰으로 계속 사용됩니다.

Android, iOS 환경에서는 PreInit()으로 결제 환경 초기화가 완료되어 추가로 호출할 필요는 없습니다.

파라미터

• callback 완료 시 결과를 수신하는 콜백

  • BillingPlatofrm.BillingResultCode 세부 설명 아래 참고

//1. 결제 환경 초기화
bool bOk = BillingPlatform.Instance.Prepare( (resultCode) =>
{
    //TODO
});

BillingPlatform.BillingResultCode

public enum BillingResultCode
{
    OK,                  // 성공
    UNSUPPORTED_STORE,   // 지원하지 않는 스토어
    AGENT_NOT_REGISTERED // BillingAgent
	  FAIL,                // 기타 오류
}

결제 환경 초기화 후에 판매할 상품에 대한 정보를 조회할 수 있습니다.

상품 조회

판매할 상품 정보를 조회합니다. 결제 플랫폼 연결 후에 조회할 수 있습니다.

상품 조회 결과 상품의 상세 정보(상품명, 가격 등)을 확인 할 수 있습니다.

1개 이상의 상품 정보를 조회할 수 있습니다.

결제 플랫폼 별로 상이하며, 개수가 많아지면 오류가 발생할 수 있습니다.

소량의 개수를 반복해서 조회하세요.

BillingPlatform.QueryProductDetails

void QueryProductDetails(string[] products, Action callback)
void QueryProductDetails(string[] products, Dictionary<string, object> queryParams, Action callback)

결제 환경 초기화 후에 판매할 상품에 대한 정보를 조회할 수 있습니다.

string[] products = new string[] 
                { 
                    "item.bag.blue", 
                    "item.bag.brown" 
  });

BillingPlatform.Instance.QueryProductDetails(products, () =>
{
	//TODO : 조회상품 상세 정보 확인
});

엑솔라 상품 조회는 추가 파라미터가 필요합니다.

1개 이상의 상품을 조회할 수 있습니다.

엑솔라는 1개 상품 만을 조회하는 기능을 제공하기 때문에 조회할 상품 개수가 많은 경우 응답 시간이 매우 길어 질 수 있습니다.

백드라운드에서 미리 상품 조회를 통해 상품 정보를 구성하세요.

string[] products = new string[] { "item.bag.blue" });
var queryParams = new Dictionary<string, object>()
{
    ["imid"] = "87DDCADUCX7WLK7D11HY",
    ["playerId"] = "playerId",
    ["playerNameValue"] = "캐릭터이름"
};

BillingPlatform.Instance.QueryProductDetails(products, queryParam, () =>
{
	//TODO : 조회상품 상세 정보 확인
});

판매 상품 세부 정보 확인

상품 조회(IBillingAgent.QueryProductDetails()) 결과는 ProductManager에 저장됩니다.

ProductorManager.GetProduct

public ProductDetails GetProduct(string productId)

상품 상세 정보를 담고 있는 ProductDetails 객체가 리턴 됩니다.

public class ProductDetails
{
    public string productId;
    public string inappType;
    public string name;
    public string description;
    public long priceAmountMicros;
    public string priceCurrencyCode;
    public string formattedPrice;
    public string skuDetailsToken;
}

필드명	설명	예시
productId	스토어에 등록된 아이템 ID	item.bag.blue
inappType	상품 종류	inapp
name	스토어에 등록한 상품명	가방(블루)
description	스토어에 등록한 상품 설명	파란색 가방
priceAmountMicros	micro 상품 가격	1200000000
priceCurrencyCode	통화	KRW
formattedPrice	스토어에 출력될 가격 표기 문구	₩1,200
skuDetailsToken	안드로이드 sku details (서버 로그용)

상품 구매

상품을 구매 프로세스를 시작합니다.

구매 결과는 아래 콜백으로 수신 됩니다.

• 성공 : OnPurchasesUpdated()

• 취소 : OnPurchasesCanceled()

• 에러 : OnPurchasesError

스팀 결제는 스팀서버 → 클라이언트로 결제팝업을 띄우는 구조로 구매 시작을 StartPurchase 를 사용하지 않습니다.

public void BillingPlatform.StartPurchase

예약된 상품을 구매합니다.

구매 결과는 IBillingAgetnt 콜백 함수로 전달됩니다.

public bool StartPurchase(string productId, string boid)

파라미터

• projectId 구매할 상품 ID

• boid 상품 예약 시 리턴 받은 boid 값

리턴

• true : 상품 구매 프로세스가 정상적으로 실행되는 경우

• false : 상품 구매 프로세스가 실패 한 경우

  • 결제 모듈 초기화 실패

  • 결제 진행 중인 상품이 있는 경우 등

상품 구매 전 게임 서버에게 우선 구매할 상품을 예약해야 합니다. 게임 서버에 상품 예약을 요청하고, 예약 결과로 수신한 boid 를 구매 시 사용합니다.

상품을 구매하기 위해서는 BillingPlatform.StartPurchase()를 호출한다.

public bool StartPurchase(string productId)
{
			//1. 구매 가능 상태인지 검사한다.
      if(BillingPlatform.Instance.CanPurchable() == false)
          return false;

			//2. 게임서버에게 구매할 상품을 예약한다.
      string boid = 게임서버상품예약요청(productId);

			//3. 상품 구매 프로세스를 시작한다.
			return BillingPlatform.Instance.StartPurchase(productId, boid);
}

void ContinuePurchase

상품 구매 프로세스를 계속 진행 합니다.

결제 상태를 클라이언트에서 직접 받지 못하는 결제 프로세스에서 사용됩니다. Google Play PC는 브라우저에서 결재를 진행 한 후 인게임에서 ContinuePurchase를 호출해야합니다.

public void ContinuePurchase()

파라미터

• 없음

리턴

• 없음

상품 구매 이벤트 핸들러 구현

상품을 구매 프로세스를 시작하면, 구매 결과는 아래 콜백으로 수신 됩니다.

• 성공 : OnPurchasesUpdated

• 취소 : OnPurchasesCanceled

• 에러 : OnPurchasesError

• 소비처리 안된 구매 : OnUnconsumedPurchasesUpdated

• 스팀 결제창 Close : OnContinueSteamPurchase

IBillingAgent를 구현한 클래스에서 다음 이벤트 핸들러를 반드시 구현해야 합니다.

public void OnPurchasesUpdated

결제 완료 시 호출되는 이벤트 핸들러.

public override void OnPurchasesUpdated(string boid, string resultJson)

파라미터

• boid 상품 예약 시 리턴 받은 boid 값

• resultJson 구매 영수증 JSON

결제가 성공하면, 아래 작업을 반드시 진행해야 최종 구매가 확정되어 구매한 상품이 유저에게 전달됩니다.

• 게임 서버를 통해 영수증을 검증

• 게임 서버를 통한 소비 처리

  • 클라이언트에서 소비 처리를 하지 않고 플랫폼 결제 백엔드를 통해서 소비 처리를 합니다.

게임 서버에 영수증을 전달하면 검증을 통해 백엔드 서버에서 소비 처리가 이루어집니다.

결제 플랫폼에 따라 영수증(JSON) 포맷이 다르게 전달될 수 있습니다. 구매 상품 영수증을 참고하세요.

public void OnUnconsumedPurchasesUpdated

소비 처리되지 않은 구매 건 발생 시 호출되는 이벤트 핸들러.

Android, Google Play PC, iOS 에서 발생할 수 있습니다.

public override void OnUnconsumedPurchasesUpdated(string boid, string resultJson)

파라미터

• boid 상품 예약 시 리턴 받은 boid 값

• resultJson 구매 영수증 JSON

앱 실행 후 PreInit()으로 결제 환경을 초기화 하는 경우에 소비 처리되지 않은 구매 건을 조회하여 결과를 전달합니다. 파라미터는 OnPurchasesUpdated() 와 동일하며 소비 처리를 위해 아래와 같이OnPurchasesUpdated() 호출과 동일한 프로세스를 진행하면 됩니다.

• 게임 서버를 통해 영수증을 검증

• 게임 서버를 통한 소비 처리

  • 클라이언트에서 소비 처리를 하지 않고 플랫폼 결제 백엔드를 통해서 소비 처리를 합니다.

게임 서버에 영수증을 전달하면 검증을 통해 백엔드 서버에서 소비 처리가 이루어집니다.

OnPurchasesUpdated와 동일한 정보를 전달하지만, 별도의 콜백으로 전달합니다.

유저에게 해당 정보 알려주거나, 추가 프로세스가 필요한 경우에 추가 작업을 구현할 수 있습니다.

public void OnPurchasesCanceled()

결제 도중 사용자가 취소 한 경우 호출되는 이벤트 핸들러

public override void OnPurchasesCanceled()

파라미터

• 없음

public override void OnPurchasesError

결제 도중 다양한 이유로 결제 진행이 되지 않는 경우 호출되는 이벤트 핸들러

public override void OnPurchasesError(BillingErrorCode code, string message)

파라미터

• code 오류 코드

• message 오류 메시지

public enum BillingErrorCode
    {
        OK                      = 0,
        // 기타 에러
        ERROR                   = 1,
        // 사용자 취소 (reserved), OnPurchasesCanceled() 이벤트로 전달
        USER_CANCELED           = 2,
        // 구매할 수 없는 아이템
        ITEM_UNAVAILABLE        = 3,
        // 결제 에러 (미지원 국가/스토어, 결제권한 없음 등)
        BILLING_UNAVAILABLE     = 4,
        // 지원되지 않는 기능
        FEATURE_NOT_SUPPORTED   = 5,
        // 결제 서비스 이용 불가 (스토어 결제 서버 연결 오류 등)
        SERVICE_UNAVAILABLE     = 6,
        // 네트워크 오류
        NETWORK_ERROR           = 7,
        // 가격 정보 오류
        INVALID_PRICE           = 8,
        // 개발자 에러
        DEVELOPER_ERROR         = 9,
        // 알 수 없는 애러
        UNKNOWN_ERROR           = 10,
        // 결제 트랜잭션 소비 대기 중
        WAITING_FOR_CONSUME     = 11,
    }

BillingErrorCode는 공통 에러코드를 정의한 것으로 모든 스토어에 공통으로 적용됩니다.

에러 발생 시 각 스토어별 세부 에러 코드는 에러 로그 콘솔을 확인하세요.

public override void OnContinueSteamPurchase

스팀 결제 창이 닫힌 후 호출되는 이벤트 핸들러.

스팀은 결제 상태(성공, 취소) 정보를 클라이언트에 직접 제공하지 않습니다.

게임 서버에 예약된 boid 상품에 대한 결제 진행을 요청해야 합니다. 이후 최종 결제 상태는 게임 서버를 통해 수신해야 합니다.

public override void OnContinueSteamPurchase(string boid)

파라미터

• boid 예약 boid, BillingPlatform.ContinueSteamPurchase() 호출 시 전달한 boid

상품 구매 프로세스 이벤트 전송

IOS 구매 시에만 필요합니다.

상품 결제 후 게임 서버와 구매 프로세스를 완료한 후에 BillingPlatform으로 구매 결과 전달해야 합니다.

void OnCompletedPurchase

void OnCompletedPurchase(string boid, bool purchased)

파라미터

• boid 예약ID

• purchased 구매 성공시 true

구매 상품 영수증

상품 결제 완료시 호출되는 이벤트에 영수증 데이터가 JSON으로 전달됩니다.

결제 플랫폼에 따라 영수증(JSON) 포맷이 다르게 전달됩니다.

Google Play PC 영수증

{
  "microPrice": 1200000000,
  "currency": "KRW",
  "productId": "item.bag",
  "purchaseToken": "string"
}

PlayStore(Android), AppStore 영수증

{
  "microPrice": 2200000000,
  "currency": "JPY",
  "productDetailsJson": "string",
  "purchaseOriginalJson": "string",
  "purchaseSignature": "string"
}

public override void OnPurchasesUpdated(string boid, string resultJson)

전달되는 JSON은 PurchaseDetails 로 확인할 수 있습니다.

public class PurchaseDetails
{
    public long microPrice;                       // 구매 상품 가격, micro 단위
    public string currency;                       // 상품 가격 표시 단위
    public string signature;                      // 구매 signature
    public string originalJson;                   // 주문 상세 정보 JSON
    public List<ProductDetails> productDetails;   // 상품 상세 정보
    public static PurchaseDetails FromJson(string json)
    {
        return JsonConvert.DeserializeObject<PurchaseDetails>(json);
    }
}

속성	설명	지원 플랫폼
microPrice	매 상품 가격, micro 단위	ALL
currency	상품 가격 표시 단위. ex)KRW	ALL
signature	구매 검증 데이터	AOS : 구매 signature iOS: 구매 영수증(Receipt)
originalJson	안드로이드 결제 데이터(JSON)	AOS
productDetails	구매 상품 정보	AOS

사용 예

public override void OnPurchasesUpdated(string boid, string resultJson)
{
    var purchaseDetails = PurchaseDetails.FromJson(resultJson)
}

구매 한도 및 연령 확인

상품 구매 시 진행하는 상품 예약 단계 에서 국가 별 결제 정책에 따라서 게임 서버로 부터 다음과 같은 사유로 예약 실패가 발생할 수 있습니다. 각 사유에 대한 코드는 서버 담당자에게 문의하세요.

• 구매 한도 초과

• 연령 확인 필요

위의 사유에 해당하는 경우, 아래 정책을 반영하세요.

• 구매 한도 초과 → 외부 브라우저에서 계정 센터를 띄우세요

• 연령 확인 필요 → 인 게임 웹뷰에서 연령 입력 페이지를 띄우세요.

계정 센터 및 연령 입력 페이지는 PlatformSupervisor.GetUrl 을 통해 구할 수 있습니다.

{
  "microPrice": 1200000000,
  "currency": "KRW",
  "productId": "item.bag",
  "purchaseToken": "string"
}

미처리된 영수증 처리

다양한 이유로 결제가 완료되었지만 상품이 지급되지 않은채 미처리된 영수증이 발생할 수 있습니다. 그런 상황에서 상품 프로세스를 실행하는 API 입니다.

BillingPlatform.Restore

미처리된 영수증 단 건에 대해 복구합니다. 이 함수는 상품 구입은 했지만 앱 상태는 유지되면서 지급이 되지 않았을 때, 동일한 boid로 다시 시도하는 용도로 사용될 수 있습니다.

void Restore(string boid)

BillingPlatform.RestoreAll

미처리된 모든 영수증에 대해 복구를 시도합니다.

상품구입 컨텍스트가 끊어졌을 때 boid를 모르는 경우 사용할 수 있습니다. PreInit 단계에서 수행하는 미처리 영수증 조회와 동일한 기능을 수행합니다.

void RestoreAll()

로그 레벨

SDK는 다양할 로그를 출력하고 있으며 로그 레벨 지정을 통해 출력 되는 로그를 제어할 수 있습니다.

PlatformSupervisor.SetLogLevel

스팀 결제 창이 닫힌 후 호출되는 이벤트 핸들러.

void SetLogLevel(LogLevel logLevel, bool enableFileLog = false)

파라미터

• logLevel 로그 레벨 (Debug, Info, Warn, Error)

• enableFileLog 파일 저장 여부, Windows 에서만 지원합니다.

Debug 로그 레벨은 개발 목적으로 사용하세요.

배포 빌드에서는 Info 레벨 이상을 사용하세요.

로그 파일 저장은 스팀 연동 테스트 같은 로그 확인이 어려운 개발 환경에서 사용하세요. 로그 파일 저장 위치 : c:\Users\사용자명\hyplatform\hylog.log

안드로이드 결제 Troubleshooting

결제 창이 나오지 않습니다.

Play Store에 업로드한 최신 빌드의 버전이 테스트 중인 버전과 동일한지 확인하세요.

실행 버전이 Play Store에 등록된 버전과 다를 경우 결제 창이 나오지 않습니다.

테스트 카드 결제가 되지 않습니다.

라이선스 테스트에 테스트하는 계정이 등록되어 있는지 확인하세요.

Google Play Console > 설정 > 라이선스 테스트

구입하려는 항목을 찾을 수 없습니다

해당 계정이 테스터 참여 수락이 안 된 상황입니다. 테스터 페이지에 있는 링크에서 수락참여를 해야합니다.

Google Play Console > 홈 > (테스트할 앱) > 테스트 > 내부 테스트 > 테스터 > 테스트 참여방법 항목의 “링크 복사”

스팀 결제 창이 나오지 않습니다.

스팀 오버레이 기능으로 스팀 결제 창이 팝업 됩니다. 스팀 앱에서 오버레이 기능이 비활성화 되어 있는 경우 스팀 결제 창이 나오지 않습니다.

스팀 결제를 진행하기 전에 반드시 오버레이가 활성화 되어있는지 조회 후 진행 해야 합니다. 아래 API를 참고하세요.