상품 목록 조회와 구매

상품 목록 조회¶

게임 내 상점 진입 시 상품 목록 조회 API를 호출해야 합니다. 상품 목록 요청을 수행하면 결과 통지 시 IAPV4Product 클래스에 상품 목록 정보를 포함하여 반환합니다.

상품 정보 정의¶

displayPrice¶

• 통화 기호와 가격을 조합한 형태(예: $0.99)로 displayPrice를 전달합니다. Android와 iOS의 노출 방식이 다르기 때문에 일부 국가에서는 OS에 따라 통화 기호와 가격 순서가 다를 수 있습니다.
• 각 나라의 통화기호는 통화기호표와 동일하게 출력합니다. 통화기호는Hive 식별자 정책을 참고하세요.
• 다른 나라에서 부가세를 추가하거나 변동하는 경우에 서버에서 계산하여 displayPrice, price, displayOriginalPrice, originalPrice에 반영하므로 추가 작업이 필요 없습니다.

상품 목록을 조회하려면 IAPV4 클래스의 getProductInfo() 메서드를 호출하고 결과값으로 상품 목록의 상품 정보, 러비 잔액을 전달 받습니다.

다음은 상품 목록 조회를 요청하는 예제 코드입니다.

using hive;    
    IAPV4.getProductInfo((ResultAPI result, List<IAPV4Product> productInfoList, int balance) => {    
         if (result.isSuccess()) {    
            // call successful    
        }    
});

#include "HiveIAPV4.h"

FHiveIAPV4::GetProductInfo(FHiveIAPV4OnProductInfoDelegate::CreateLambda([this](const FHiveResultAPI& Result, const TArray<FHiveIAPV4Product>& ProductInfoList, uint32 Balance) {
        if (Result.IsSuccess()) {
                // API 호출 성공
        }
}));

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    IAPV4::getProductInfo([=](ResultAPI const & result, vector<IAPV4Product> const & productInfoList, unsigned int balance) {    
         if (result.isSuccess()) {    
         // call successful    
         }    
});

import com.hive.IAPV4    
    import com.hive.ResultAPI    
    IAPV4.getProductInfo(object : IAPV4.IAPV4ProductInfoListener {    
         override fun onIAPV4ProductInfo(result: ResultAPI, iapV4ProductList: ArrayList<IAPV4.IAPV4Product>?, balance: Int) {    
             if (result.isSuccess) {    
                 // call successful    
             }    
         }    
})

import com.hive.IAPV4    
    import com.hive.ResultAPI    
    IAPV4.INSTANCE.getProductInfo((result, iapV4ProductList, balance) -> {    
         if (result.isSuccess()) {    
             // call successful    
         }    
});

import HIVEService    
    IAPV4Interface.getProductInfo() { result, productInfoList, balance in    
        if result.isSuccess() {    
            // call successful    
        }    
}

#import <HIVEService/HIVEService-Swift.h>    
    [HIVEIAPV4 getProductInfo: ^(HIVEResultAPI *result, NSArray<HIVEIAPV4Product *> *productInfoList, NSUInteger balance) {    
         if ([result isSuccess]) {    
            // call successful    
         }    
}];

상품 구매¶

Hive IAP v4에서 상품 구매는 App Store, Play Store에 등록된 marketPid를 매개변수로 IAPV4 클래스의 purchase() 메서드를 호출하여 요청합니다.

다음은 상품 구매를 요청하는 예제 코드입니다.

using hive;    
    String marketPid = "{YOUR_PRODUCT_MARKET_PID}";    
    String iapPayload = "{YOUR_CUSTOM_PAYLOAD}"    

    IAPV4.purchase(marketPid, iapPayload, (ResultAPI result, IAPV4Receipt receipt) => {    
    if (result.isSuccess()) {    
             // TODO: Request verification of receipt with received receipt    
         }    
});

#include "HiveIAPV4.h"

FString MarketPid = TEXT("YOUR_PRODUCT_MARKET_PID");
FString IapPayload = TEXT("YOUR_CUSTOM_PAYLOAD");

FHiveIAPV4::Purchase(MarketPid, IapPayload, FHiveIAPV4OnPurchaseDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveIAPV4Receipt& Receipt) {
        if (Result.IsSuccess()) {
                // API 호출 성공
        }
}));

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    string marketPid = "{YOUR_PRODUCT_MARKET_PID}";    
    string iapPayload = "{YOUR_CUSTOM_PAYLOAD}";    
    IAPV4::purchase(marketPid, iapPayload, [=](ResultAPI const & result, IAPV4Receipt const & receipt) {    
         if (result.isSuccess()) {    
             // TODO: Request verification of receipt with received receipt    
         }    
});

import com.hive.IAPV4    
    import com.hive.ResultAPI    
    val marketPid = "{YOUR_PRODUCT_MARKET_PID}"    
    val iapPayload = "{YOUR_CUSTOM_PAYLOAD}"    
    IAPV4.purchase(marketPid, iapPayload, object : IAPV4.IAPV4PurchaseListener {    
         override fun onIAPV4Purchase(result: ResultAPI, iapV4Receipt: IAPV4.IAPV4Receipt?) {    
             if (result.isSuccess) {    
                 // call successful    
             }    
         }    
})

import com.hive.IAPV4;    
    import com.hive.ResultAPI;    
    String marketPid = "{YOUR_PRODUCT_MARKET_PID}";    
    String iapPayload = "{YOUR_CUSTOM_PAYLOAD}";    
    IAPV4.INSTANCE.purchase(marketPid, iapPayload, (result, iapV4Receipt) -> {    
         if (result.isSuccess()) {    
             // call successful    
         }    
});

import HIVEService    
    let marketPid = "{YOUR_PRODUCT_MARKET_PID}"    
    let iapPayload = "{YOUR_CUSTOM_PAYLOAD}"    

    HIVEIAPV4.purchase(marketPid, iapPayload: iapPayload) { result, receipt in    
         if result.isSuccess() {    
             // TODO: Request verification of receipt with received receipt    
         }    
}

#import <HIVEService/HIVEService-Swift.h>

NSString *marketPid = @"{YOUR_PRODUCT_MARKET_PID}";
NSString *iapPayload = @"{YOUR_CUSTOM_PAYLOAD}";

[HIVEIAPV4 purchase: marketPid iapPayload: iapPayload handler: ^(HIVEResultAPI *result, HIVEIAPV4Receipt *receipt) {
    if ([result isSuccess]) {
        // TODO: Request verification of receipt with received receipt
    }
}];

iapPayload 활용¶

구매(purchase()) 또는 구독(purchaseSubscription) 메서드를 실행할 때, 게임사는 iapPayload를 인자로 넘길 수 있습니다. iapPayload는 게임사에서 자체 정의한 구매 메타데이터입니다. 예를 들면, 어떤 유저가 상품을 구매했을 때 구매 시간, 상품을 구매한 유저 정보, 구매한 게임 캐릭터 정보, 구매 수량(소모성 아이템), 구매 토큰 등일 수 있습니다.

iapPayload를 인자로 넘기면 Hive IAP 서버가 구매 영수증을 검증할 때 이 iapPayload값이 어떤 구매 영수증에 해당하는 값인지 매칭하여 게임 서버에 알려줍니다. 정확히는, iapPayload값과 영수증 고유 키에 해당하는 hiveiap_transaction_id값을 매칭하여 게임 서버에 전달합니다.

구매 영수증과 iapPayload 짝을 활용하면 다양한 문제를 해결할 수 있습니다. 예를 들어, 유저가 아이템 구매 시 에러가 발생해 결제는 끝났지만 아이템을 지급하지 못한 상황이 있을 수 있습니다. 이 때, restore() 메서드를 실행하면 유저가 아이템을 구매한 영수증을 얻을 수는 있지만, 이 영수증에는 유저에게 지급해줘야할 아이템이 어떤 종류의 아이템인지, 몇 시에 구매한 아이템인지, 어떤 캐릭터가 구매한 아이템인지 정보는 존재하지 않기 때문에 어떤 아이템을 유저에게 지급해야 하는지 알 수가 없습니다. 하지만, 구매 영수증과 짝지어진 iapPayload를 통해 이 정보들을 알 수 있어 유저에게 아이템을 지급할 수 있습니다.

소모성 아이템 구매 수량 설정¶

Google Play Store에서는 유저가 장바구니에서 수량을 지정해 한 번의 거래로 같은 인앱 상품을 두 개 이상 구매할 수 있습니다. Google Play Console 상품 설정에서 다중 수량 구매를 허용하면 앱은 다중 수량 구매를 처리하고 지정한 구매 수량에 따라 아이템을 지급해야 합니다. 단, 다중 수량 구매는 소비 후 다시 구매할 수 있는 상품인 소모성 인앱 상품을 위한 것입니다. 반복적으로 구매할 수 없는 상품에는 이 기능을 사용하도록 설정하지 마세요.

purchase() 메서드 호출 시 주의사항¶

• purchase() 메서드를 호출하는 도중 마켓 오류로 RESPONSE_FAIL, CANCELED 에러가 발생하면 사용자에게 구매 과정에 문제가 있음을 알립니다.
• 구매 과정에 문제가 있다는 알림을 사용자가 확인했다면 restore() 메서드를 호출하여 구매 복구를 진행합니다.
• purchase() 메서드를 호출하는 도중 NEED_RESTORE 에러가 발생하면 구매가 취소되며, 이 경우 restore()메서드를 호출하여 구매 복구를 진행합니다.
• purchase() 메서드를 호출하는 도중 오프라인 결제를 시도하는 경우 또는 미성년자 가족 구성원이 부모에게 아이템 결제를 요청하는 경우 ITEM_PENDING 에러가 발생하며 해당 아이템은 구매 대기 상태가 됩니다. 부모가 미성년 가족을 대신해 구매하는 기능은 현재 Google Play Store, Amazon 마켓, Apple App Store만 지원합니다.
• 오프라인 결제 성공한 경우 또는 부모가 미성년자 가족 구성원에게 요청받은 아이템 결제를 승인하는 경우 UserEngagement를 통해 `IAP_UPDATED` 이벤트를 수신합니다. UserEngagement eventEnd 콜백으로 파라미터를 전달받을 때 `type`이 "subscription"이면 `restoreSubscription()`, `type`이 비어있는 경우 `restore()` 메서드를 호출하세요. 결제 완료 상품의 영수증 정보를 확인할 수 있습니다.
• 인앱 구입 차단 문구 가이드를 참고하면 필요에 따라 NOT_SUPPORTED 에러 처리로 사용자가 구매 할 수 없는 상태임을 알릴 수 있습니다.
• 데스크톱 환경에서 HIVESTORE로 구매하는 경우에는 새 창에서 결제 요청 화면이 노출됩니다. `hive.IAPV4.purchase(marketPid, null, onIAPV4PurchaseCB);`를 호출하면 영수증 정보 없이 `onIAPV4PurchaseCB`를 통해 ErrorCode:IAPSUCCESS=90와 Code:IAPV4HiveStoreSuccess=-6110000의 응답을 즉시 반환하며, ErrorCode(또는 Code)를 판별하여 아이템 지급 가능 상태에 대한 안내 메시지를 노출할 수 있습니다.
• Google Play용 Windows 앱(Hive SDK v4 Unity Windows 23.0.0 이상)에서 `GOOGLE_PLAYSTORE` 마켓을 사용할 때, 결제용 Google 계정의 인증 정보가 만료되면, Hive SDK는 자동으로 재인증 과정을 실행합니다.
• Google Play용 Windows 앱(Hive SDK v4 Unity Windows 23.0.0 이상)에서 `GOOGLE_PLAYSTORE` 마켓을 사용할 때, 사용자가 앱상에 나타난 결제 대기 팝업의 확인 버튼을 눌렀을 때, 결제 완료 여부가 확인되지 않은 경우 `onIAPV4PurchaseCB`로 `ErrorCode:IAPSUCCESS=90`과 `Code:IAPV4PendingPurchase=-6100013` 응답을 반환합니다. 이 응답은 결제에 실패한 상황이 아니며, 사용자가 돈을 지불했지만 내부 오류로 결제 완료가 확인되지 않았거나, 사용자가 결제를 하지 않은 경우에 해당합니다. 이 경우 영수증을 반환하지 않으며, 사용자가 결제 브라우저 창에서 결제를 완료했다면 `IAPV4.restore`로 영수증을 얻을 수 있습니다.

구매 에러코드¶

인앱 구매 차단 문구¶

청약 철회 규정¶

콘텐츠산업 진흥법에 따라 게임 상점에 청약 철회에 대한 안내문과 청약 철회 규정 안내 링크를 제공하세요. iOS의 경우 Apple 검수 과정에서 청약 철회 안내 문구가 노출되면 게임 앱 심사 거절 사유가 될 수 있습니다.