Unreal Engine 빌링

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

요구사항

빌링 플랫폼 SDK를 사용하기 위한 요구 사항은 다음과 같습니다.

• OS : Windows

• Enreal Engine : 5.2.1

• Visual Studio 2019 이상

결제 SDK는 언리얼 플러그인으로 제공되는 플랫폼 SDK와 함께 제공되고 있습니다.

연동 준비

SDK 설치

언리얼 엔진에서 Platform SDK를 사용하기 위해서는 배포된 플러그인을 프로젝트의 Plugins 복사합니다.

SDK 설치 가이드를 참고하세요.

스팀 결제 환경 설정

플랫폼에 제공하는 별도의 설정은 필요하지 않습니다. 스팀앱에 로그인 상태이어야 합니다.

스팀에서 게임을 실행하거나, 언리얼 에디터에서 실행하는 경우 스팀 오버레이 결제 팝업을 통해서 결제를 진행합니다.

스팀앱에서 오버레이 기능이 활성화 되어 있어야 합니다.

게임의 속성 페이지에서 오버레이 활성화 상태를 설정할 수 있습니다 (디폴트 ON)

• 게임 선택 > 관리(⚙️) 버튼 > 속성 선택

API 연동

API Flow (스팀)

스팀 결제는 게임 클라이언트에서 스팀 서버에 결제를 요청하지 않고 게임 서버를 통해 서버 to 서버로 구매를 요청해야 합니다.

아래 결제 플로우에서 파란색으로 표기된 프로세스를 게임에서 구현해야 합니다.

Steam Billing Flow

API 적용 순서 (Steam)

1. HybeBillingAgent 상속 클래스 작성

2. HybeBillingPlatform에 1)에 추가한 인스턴스 등록

3. 빌링 플랫폼 연결

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

   1. 상점 UI 구성

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

   1. 상품 예약 후 결제 팝업

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

   1. OnContinueSteamPurchase 작성

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

Billing 클래스

Platform Billing Class

클래스	개발담당	설명
HybeBillingPlatform	SDK	빌링 플랫폼 결제 기능을 제공하는 메인 클래스
HybeBillingAgent	SDK	결제 과정에서 발생하는 이벤트를 정의한 인터페이스
HybeProductManager	SDK	상품 상세정보 관리 기능 제공
ProductDetail	SDK	상품 상세 정보 (상품명, 가격, 통화 등)
StarterBillingAgent	개발사	게임 클라이언트에서 결제 이벤트 수신을 위해 구현해야 하는 클래스.

HybeBillingPlatform

빌링 플랫폼 결제 기능을 제공하는 메인 클래스.

빌링 플랫폼 연결, 상품 조회 및 구매 기능을 제공한다.

class HybeBillingPlatform : public Singleton<HybeBillingPlatform>
{
public:
    void PreInit(const FString& imid);
    void QueryProductDetails(const TArray<FString>& products, const std::function<void(bool)>& callback);
    void ContinueSteamPurchase(const FString& boid);
    bool CanPurchable();
    bool IsReady();
    
    HybePlatform::StoreType GetStore() const;
    HybePlatform::PaymentType GetPlayment() const;
    FString GetStoreName() const;
    FString GetPlaymentName() const;
    FString GetOsName() const;
};

HybeBillingPlatform ::PreInit

빌링 플랫폼 초기화 . 플랫폼 결제 환경에 연결합니다.

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

결과는 Billing Agent의 OnPrepared() 이벤트로 전달됩니다.

void PreInit(const FString& imid)

파라미터

• imid Player ID (IMID)

HybeBillingPlatform ::QueryProductDetails

빌링 플랫폼에 판매할 상품 정보를 요청합니다.

수신된 상품 정보는 HybeProductManager를 통해 조회할 수 있습니다.

HybeProductManager를 통해 상품을 조회한 후, 상품 정보가 없는 상품에 대해서 QueryProductDetails를 호출해서 상품 정보를 HybeProductManager에 등록합니다.

void QueryProductDetails(
    const TArray<FString>& products, const std::function<void(bool)>& callback)

파라미터

• products 조회할 상품 ID 배열

• callback 결과를 수신할 콜백

QueryProductDetails 호출 예

TArray<FString> products = { TEXT("item_01"), TEXT("item_02") };
GetBillingPlatform().QueryProductDetails(products, [](bool result)
{
    if (result)
    {
    }
});

HybeBillingPlatform ::ContinueSteamPurchase STEAM

빌링 플랫폼에 스팀 결제 프로세스 모니터링을 요청합니다.

게임 서버에 결제 요청을 전달 후에 스팀이 띄워주는 결제 창에서 결제 완료 상태를 수신하기 위해서 호출합니다. 결과는 BillingAgent의 OnContinueSteamPurchase()으로 이벤트가 전달됩니다.

스팀 결제는 클라이언트의 요청으로 시작되지 않고, 플랫폼 결제 서버에서 스팀 결제 서버로 결제 요청을 통해 시작됩니다.

플랫폼 결제 서버 --> 스팀 결제 서버 --> 스팀 앱 --> 게임 클라이언트 결제 창

void ContinueSteamPurchase(const FString& boid)

파라미터

• boid 상품 예약 ID

HybeBillingPlatform ::IsReady

빌링 플랫폼 연동 상태를 조회합니다.

bool IsReady()

파라미터

• 없음

리턴

• PreInit() 호출 후 빌링 플랫폼을 사용할 수 있는 경우 true, 빌링 플랫폼 연동이 실패한 경우 false

HybeBillingPlatform ::CanPurchable

상품이 구매 가능한지 조회합니다.

bool CanPurchable()

파라미터

• 없음

리턴

• 상품 결제가 가능하면 true, 그렇지 않으면 false

HybeBillingPlatform::GetStore, HybeBillingPlatform::GetStoreName

연동된 결제 스토어 종류를 조회합니다.

HybePlatform::StoreType GetStore() const
FString GetStoreName() const

파라미터

• 없음

리턴

• 연동된 결제 스토어 종류 StoreType

• 연동된 결제 스토어 종류 StoreType 문자열

    enum StoreType
    {
        GOOGLE_PLAY,
        APPLE_APP_STORE,
        STEAM,
        GOOGLE_PLAY_PC,
        IM_LAUNCHER,
        GALAXY_STORE,
        ONE_STORE,
        DMM
    };

HybeBillingPlatform::GetPayment, HybeBillingPlatform::GetPaymentName

연동된 결제 수단 종류를 조회합니다.

HybePlatform::PaymentType GetPlayment()
FString GetPlaymentName() const

파라미터

• 없음

리턴

• 연동된 결제 수단 종류 PaymentType

• 연동된 결제 수단 종류 문자열

    enum PaymentType
    {
        GOOGLE_PLAY,
        APPLE_APP_STORE,
        STEAM,
        DMM,
        XSOLLA,
        MYCARD
    };

HybeBillingPlatform::GetOsName

실행 중인 OS 이름을 조회합니다.

FString GetOsName() const

파라미터

• 없음

리턴

• 실행 중인 OS 명

    enum OsType
    {
        ANDROID,
        IOS,
        MACOS,
        LINUX,
        WIN64,
        WIN32
    }

HybeBillingAgent

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

class HybeBillingAgent
{
public:
    void OnPrepared(BillingResultCode result) = 0;
    void OnPurchasesUpdated(const FString& boid, const FString& resultJson) = 0;
    void OnPurchasesCanceled() = 0;
    void OnPurchasesError(BillingErrorCode code, const FString& message) = 0;
    void OnUnconsumedPurchasesUpdated(const FString& boid, const FString& resultJson) = 0;
    void OnRestoreFinished(const TArray<UnconsumedPurchaseDetails>& details) = 0;
    void OnContinueSteamPurchase(const FString& boid) = 0;
};

HybeBillingAgent::OnPrepared

void OnPrepared(BillingResultCode result)

결제 환경이 준비된 후 호출되는 이벤트.

파라미터

• result 결과 코드(BillingResultCode)

enum class BillingResultCode
{
    OK = 0,
    UNSUPPORTED_STORE = 1,   // 지원하지 않는 스토어
    UNREGISTERED_AGENT = 2,  // BillingAgent 미등록
    FAIL = 3,                // 기타 오류
};

HybeBillingAgent::OnContinueSteamPurchase STEAM

void OnContinueSteamPurchase(const FString& boid)

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

이벤트를 수신한 게임 클라이언트는 게임 서버에게 구매 완료를 요청해야 합니다.

결제 상태(완료/취소)는 클라이언트로 전달되지 않기 때문에 서버에 완료 처리를 요청합니다.

파라미터

• boid 예약 ID

HybeBillingAgent::OnPurchasesUpdated PC IOS Android

void OnPurchasesUpdated(const FString& boid, const FString& resultJson)

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

게임 클라이언트에서 결제를 진행하는 스토어인 경우 호출됩니다.

ex) PlayStore, AppStore에서 결제 완료 후

파라미터

• boid 상품 예약 ID, 상품 구매 전 게임 서버에 상품 예약 요청으로 수신 한 예약 ID

• resultJson 구매 영수증 JSON

HybeBillingAgent::OnPurchasesCanceled IOS Android

void OnPurchasesCanceled()

결제 취소 시 호출되는 이벤트 핸들러

게임 클라이언트에서 결제를 진행 도중 사용자가 취소를 하는 경우에 호출됩니다.

스팀 결제 창에서 취소를 선택하는 경우에는 호출되지 않습니다.

스팀의 경우 결제 창이 닫히면 OnContinueSteamPurchase 가 호출 됩니다.

파라미터

• 없음

HybeBillingAgent::OnPurchasesError PC IOS Android

void OnPurchasesError(BillingErrorCode code, const FString& message)

클라이언트에서 결제 진행 과정에서 오류가 발생한 경우에 호출됩니다.

파라미터

• code 에러 코드

• message 에러 메시지 (개발 전용)

HybeBillingAgent::OnUnconsumedPurchasesUpdated IOS Android

void OnUnconsumedPurchasesUpdated(const FString& boid, const FString& resultJson)

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

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

파라미터

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

• resultJson 구매 영수증 JSON

HybeProductManager

판매할 상품의 상세 정보(sku)를 관리하는 기능을 제공합니다.

HybeBillingPlatform ::QueryProductDetails 을 사용하여 스토어에 상품을 조회하면 ProductManager에 조회한 상품 정보가 등록됩니다.

HybeProductManager::GetProduct

ProductDetail GetProduct(const FString& prodectId)

파라미터

• productId 상품 ID

리턴

• 상품 상세 정보

ProductDetail

상품 상세 정보

class ProductDetail
{
public:
    FString productId;
    UINT productIdNo;        // Product Id Number : Steam Only
    FString inappType;
    FString name;
    FString description;
    int64_t priceAmountMicros;
    FString priceCurrencyCode;
    FString formattedPrice;
    FString skuDetailsToken;
    FString deepLink;        // 웹 결제 딥링크(웹 결제시 사용)

    bool IsPurchasable() const
    {
        return !productId.IsEmpty();
    }
};

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

API 연동 샘플

샘플앱에 결제 기능이 포함되어 있습니다.

결제 프로세스에는 게임서버가 반드시 필요합니다.

샘플앱에서 결제를 지원하도록 개발전용 더미게임서버를 통해 결제 기능을 제공합니다. 샘플앱 <--> 더미게임 서버 <--> 빌링백엔드

스팀 결제 연동

1. BillingAgent 인터페이스 구현

HybeBillingAgent 인터페이스를 상속받은 Billing Agent 클래스를 구현합니다.

class StarterBillingAgent : public HybeBillingAgent
{
public:
    void OnPrepared(BillingResultCode result) override;
    void OnPurchasesUpdated(const FString& boid, const FString& resultJson) override;
    void OnPurchasesCanceled() override;
    void OnPurchasesError(BillingErrorCode code, const FString& message) override;
    void OnUnconsumedPurchasesUpdated(const FString& boid, const FString& resultJson) override;
    void OnRestoreFinished(const TArray<UnconsumedPurchaseDetails>& details) override;
    void OnContinueSteamPurchase(const FString& boid) override;
};

2. BillingAgent 등록

BillingAgent 를 빌링 플랫폼에 등록합니다.

빌링 플랫폼 연동(HybeBillingPlatform::PreInit) 전에 등록되어야 합니다.

// Billing Agent 등록
HybePlatformAgent::Instance().SetPlatformBillingAgent(new StarterBillingAgent());

-- 중략 --

// 플랫폼 SDK 초기화
HybePlatformAgent::Instance().Mount(config);

3. 빌링 플랫폼 연동

게임 서버 연동 후에 빌링 플랫폼에 연동합니다.

게임서버로 부터 수신한 플레이어 정보(imid)를 빌링 플랫폼에 전달합니다.

GetBillingPlatform().PreInit(imid);

4. 판매할 상품 정보 조회

스토어에 등록된 상품의 상품명, 가격 정보 등 세부 정보를 조회합니다.

TArray<FString> products = { TEXT("item_01"), TEXT("item_02") };
GetBillingPlatform().QueryProductDetails(products, [](bool result)
{
    if (result)
    {
    }
});

조회된 상품은 ProductManager에 캐싱됩니다. QueryProductDetails() 으로 빌링 플랫폼에 요청하기 전에 ProductManager에 조회한 후 상품 정보가 없는 경우 사용하면 서버 요청을 줄 일 수 있습니다.

TArray<FString> products = { TEXT("item_01"), TEXT("item_02") };
GetBillingPlatform().QueryProductDetails(products, [](bool result)
{
    if (result)
    {
       ProductDetail productDetail = HybeProductManager::GetProduct(TEXT("item_01"));
       if(productDetail.IsPurchasable())
       {
          // 상점 UI 에 상품 등
       }
    }
});

5. 구매할 상품 예약

상품을 구매하기 전에 게임 서버를 통해 구매할 상품 예약을 요청합니다. 게임 서버는 플랫폼빌링 서버에 구매할 상품을 예약한 후 예약ID (boid)를 클라이언트에 전달합니다.

게임 클라이언트는 수신한 boid를 사용해서 이후 진행되는 결제 프로세스에 사용합니다.

6. 상품 구매 요청

예약한 상품의 구매를 게임 서버에게 요청합니다. 스팀 결제는 서버 요청으로 시작됩니다.

게임 서버에서 제공하는 결제 요청 기능을 사용하세요.

7. 스팀 결제창 팝업

게임 서버에 상품 구매를 요청하면 게임 클라이언트에 스팀 결제 오버레이 창이 팝업 됩니다.

8. 스팀 결제 이벤트 받기

스팀 결제 오버레이 창에서 결제를 취소하거나 완료한 경우 게임 클라이언트가 전달됩니다.

7)에서 게임 서버에 상품 구매 요청이 성공한 경우에 이벤트를 수신하도록 호출합니다.

HybeBillingPlatform::Instance().ContinueSteamPurchase(res.boid)

스팀 결제 창이 닫힌 후 BillginAgent로 OnContinueSteamPurchase 이벤트가 전달됩니다.

void StarterBillingAgent::OnContinueSteamPurchase(const FString& boid)
{
    // 스팀 결제 창 닫힌 후 실행
}

9. 구매 완료 요청하기

스팀 결제 창이 닫힌 후 호출되는 OnContinueSteamPurchase 이벤트는 결제 정보를 가지고 있지 않습니다. 결제를 완료 또는 취소 여부를 클라이언트에서는 알 수 없기 때문에 게임 서버에 구매 완료를 요청해야 합니다.

void StarterBillingAgent::OnContinueSteamPurchase(const FString& boid)
{
    // TODO
    // 게임 서버에게 구매 완료을 요청한다.
}