상품 목록 조회와 구매

상품 목록 조회

게임 내 상점 진입 시 상품 목록 조회 API를 호출해야 합니다. 상품의 type은 소모성(consumable)과 구독형(subscription)으로 나뉘며, 구매하려는 상품 type에 따라 ItemInfo()를 필수 호출해야할 수 있습니다.

C2SModuleInappV4_ItemInfo

Request

Argument Type	Type	Description	Platform
type	string	요청 아이템 타입 – consumable: 소모성 – subscription: 구독형 – market: 마켓 상품 정보	all
marketPidList	Array	마켓 상품 정보 요청할 pid(string) 목록 (type : market 일 경우만 동작)	iOS (1.20.1.5+)

Response

Argument Type	Type	Description	Platform
type	string	요청 아이템 타입 consumable: 소모성 subscription: 구독형	all
productList	array	아이템 목록 (Dictionary) 에러 발생 상황에는 비어 있음 자세히	all

productList 배열 타입

Argument Type	Type	Description	Platform
marketPid	string	마켓에 등록된 상품의 고유 ID	all
currency	string	통화코드 예. KRW, USD	all
price	double	상품 가격	all
displayPrice	string	상품의 가격 문자열 예. $100.00 자세히	all
title	string	상품의 타이틀	all
description	string	상품 설명	all
productType	string	상품 타입 consumable: 소모성 subscription: 구독형 market 상품 요청시에는 빈 값	all
originalJson	string	마켓에서 전달된 응답 데이터	Android
displayOriginalPrice	string	할인 전 가격 문자열	All
originalPrice	long	할인 전 가격	All
iconUrl	string	상품 아이콘 (512*512)	Android
coinsReward	int	Amazon 코인 획득 금액 Amazon에서만 사용	Android

displayPrice

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

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

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

Unity®

API Reference: C2SModule.InappV4.ItemInfo

C2SModule.Parameter arg = new C2SModule.Parameter();
C2SModule.Error error;


arg[“type”] = “consumable”; // or “subscription”

if(!C2SModule.InappV4.ItemInfo(arg. out error)) {
    // 에러 발생 시 처리
}

C2SModule.Parameter arg = new C2SModule.Parameter();

C2SModule.Error error;

arg[“type”] = “consumable”; // or “subscription”

if(!C2SModule.InappV4.ItemInfo(arg. out error)) {

// 에러 발생 시 처리

}

Cocos2d-x

API Reference: C2SModuleInappV4_ItemInfo

C2SModule_Cocos2dx::C2SModuleError eror;


Json::Value arg;
arg[“type”] = “consumable”; // or “subscription”

if( ::C2SModuleInappV4_ItemInfo(strJSON.c_str(), &error ) == false)
    // 에러 발생 시 처리
}

C2SModule_Cocos2dx::C2SModuleError eror;

Json::Value arg;

arg[“type”] = “consumable”; // or “subscription”

if( ::C2SModuleInappV4_ItemInfo(strJSON.c_str(), &error ) == false)

// 에러 발생 시 처리

}

iOS

API Reference: C2SModule.InappV4 ItemInfo

NSError* error;
NSString* type = @”consumable”;  // or “subscription”
NSMutableDictionary* arg = [[NSMutableDictionary alloc] init];
[arg setObject:type forKey:@”type”];
[C2SModuleInappV4 ItemInfo:arg error:&error completionHandler:^(NSDictionary* resultArg, NSError* resultError) {
    if(resultError == nil) {
        // 성공
    }
}];

NSError* error;

NSString* type = @”consumable”; // or “subscription”

NSMutableDictionary* arg = [[NSMutableDictionary alloc] init];

[arg setObject:type forKey:@”type”];

[C2SModuleInappV4 ItemInfo:arg error:&error completionHandler:^(NSDictionary* resultArg, NSError* resultError) {

if(resultError == nil) {

// 성공

}

}];

⇡ Go to top

상품 구매

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

C2SModuleInappV4_Purchase

Request

Argument Type	Type	Description	Platform
type	string	요청 아이템 타입 consumable: 소모성 subscription: 구독형	all
pid	string	요청 아이템의 Product ID	all
additionalInfo	string	구매 완료 시 전달 받을 추가 데이터 (JSON string)	all(1.21.1.1-)
iapPayload	string	구매 메서드를 실행할 때 요청값으로 넘길 수 있는 `iapPayload`는 게임사에서 자체 정의한 구매 메타데이터입니다. 해당 구매 건에 대해서 영수증 검증 응답으로 전달받을 추가 데이터입니다. 암호화된 데이터를 사용 권장합니다.	all(1.21.1.1+)
oldMarketPid	string	Type이 subscription이고 기존에 구독 중인 상품(oldMarketPid)을 새 구독 상품(pid)으로 변경할 때 사용	all

Response

Argument Type Type Description Platform

type string 요청 아이템 타입
consumable: 소모성
subscription: 구독형 all

receipt dictionary 영수증 정보 자세히 all

receipt 딕셔너리 타입

Argument Type	Type	Description	Platform
type	string	마켓 타입 not_selected apple_appstore google_playstore hive_lebi onestore amazon_appstore samsung_galaxystore huawei_appgallery	all
additionalInfo	String	구매 시 전달한 추가 데이터 (JSON String)	android(1.21.1.1-)
iapPayload	String	구매 시 전달한 추가 데이터 (C2SModuleInappV4_Restore 콜백에선 iapPayload 정보를 전달하지 않습니다. 하지만 Purchase, Restore 모두 영수증 검증 응답에서 iapPayload를 확인할 수 있습니다.)	android(1.21.1.1+)
bypassInfo	String	Hive 영수증 검증 시 필요한 검증 데이터 (구매 영수증 포함)	all
hiveiapReceipt	String	구매 영수증 원본	all
product	Dictionary	구매 상품 정보	all

product 딕셔너리 타입

Argument Type	Type	Description	Platform
marketPid	string	마켓에 등록된 상품의 고유 ID	all
currency	string	통화코드 예. KRW, USD	all
price	double	상품 가격	all
displayPrice	string	상품의 가격 문자열 예. $100.00 자세히	all
title	string	상품의 타이틀	all
description	string	상품 설명	all
productType	string	상품 타입 consumable: 소모성 subscription: 구독형	all
originalJson	string	마켓에서 전달된 응답 데이터	Android
displayOriginalPrice	string	할인 전 가격 문자열	All
originalPrice	long	할인 전 가격	All
iconUrl	string	상품 아이콘 (512*512)	Android
coinsReward	int	Amazon 코인 획득 금액 Amazon에서만 사용	Android

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

Unity®

API Reference: C2SModule.InappV4.Purchase

C2SModule.Parameter arg = new C2SModule.Parameter();
C2SModule.Error error;


arg[“type”] = “consumable”; // or “subscription”
arg[“pid”] = “item01”;

if(!C2SModule.InappV4.Purchase(arg. out error)) {
    // 에러 발생 시 처리
}

C2SModule.Parameter arg = new C2SModule.Parameter();

C2SModule.Error error;

arg[“type”] = “consumable”; // or “subscription”

arg[“pid”] = “item01”;

if(!C2SModule.InappV4.Purchase(arg. out error)) {

// 에러 발생 시 처리

}

Cocos2d-x

API Reference: C2SModuleInappV4_Purchase

C2SModule_Cocos2dx::C2SModuleError eror;


Json::Value arg;
arg[“type”] = “consumable”; // or “subscription”
arg[“type”] = “item01”;

if( ::C2SModuleInappV4_Purchase(strJSON.c_str(), &error ) == false)
    // 에러 발생 시 처리
}

C2SModule_Cocos2dx::C2SModuleError eror;

Json::Value arg;

arg[“type”] = “consumable”; // or “subscription”

arg[“type”] = “item01”;

if( ::C2SModuleInappV4_Purchase(strJSON.c_str(), &error ) == false)

// 에러 발생 시 처리

}

iOS

API Reference: C2SModuleInappV4 Purchase

NSError* error;
NSString* type = @”consumable”;  // or “subscription”
NSString* pid = @”item01”;
NSMutableDictionary* arg = [[NSMutableDictionary alloc] init];
[arg setObject:type forKey:@”type”];
[arg setObject:pid forKey:@”pid”];


[C2SModuleInappV4 Purchase:arg error:&error completionHandler:^(NSDictionary* resultArg, NSError* resultError) {
    if(resultError == nil) {
        // 성공
    }
}];

NSError* error;

NSString* type = @”consumable”; // or “subscription”

NSString* pid = @”item01”;

NSMutableDictionary* arg = [[NSMutableDictionary alloc] init];

[arg setObject:type forKey:@”type”];

[arg setObject:pid forKey:@”pid”];

[C2SModuleInappV4 Purchase:arg error:&error completionHandler:^(NSDictionary* resultArg, NSError* resultError) {

if(resultError == nil) {

// 성공

}

}];

`Purchase()` 메서드 호출 시 주의사항

Purchase() 메서드를 호출하는 도중 마켓 오류로 FailOperation(-3), CancelOperation(-4) 에러가 발생하면 사용자에게 구매 과정에 문제가 있음을 알립니다.
구매 과정에 문제가 있다는 알림을 사용자가 확인했다면 Restore() 메서드를 호출하여 구매 복구를 진행합니다.
Purchase() 메서드를 호출하는 도중 NeedRestore(-300) 에러가 발생하면 구매가 취소되며, 이 경우 Restore()메서드를 호출하여 구매 복구를 진행합니다.
Purchase() 메서드를 호출하는 도중 오프라인 결제를 시도하는 경우, OperationPending(-29) 에러가 발생하며 해당 아이템은 구매 대기 상태가 됩니다.
오프라인 결제에 성공한 경우, UserEngagement를 통해 IAP_UPDATED 이벤트를 수신하고, Restore() 메서드 호출로 결제 완료 상품의 영수증 정보를 확인할 수 있습니다. (Android 전용 기능으로, C2SModuleUserEngagement_SetReady 호출 가이드 참고)
구매 복구 시 FailOperation(-3) 에러가 발생하면 구매를 진행할 수 없으므로 사용자에게 복구 과정에 문제가 있음을 알려야 합니다.
인앱 구입 차단 문구 가이드를 참고하면 필요에 따라 NotSupported(-6) 에러 처리로 사용자가 구매 할 수 없는 상태임을 알릴 수 있습니다.

구매 에러코드

에러	에러코드	설명
NeedInitialize	-305	초기화 진행 필요
NetworkError	-301	네트워크 에러
NotSupported	-6	구매 불가 상태 (기기 앱 내 구입 차단 등) 지원하지 않는 마켓 설정
NeedLogin	-200	구매를 진행할 수 없는 사용자 세션
InvalidArg	-2	파라미터 오류
FailOperation	-3	API가 이미 진행중 서버 오류
OperationPending	-29	오프라인 결제 시도
CancelOperation	-4	사용자에 의한 취소
NeedRestore	-300	restore API 호출 필요
RestoreNotOwnedItem	-306	구매 복구할 아이템 없음
FailCanMakePayments	-5000	InApp 구입 차단 설정 중 (iOS 전용)
UNKNOWN ERROR	-1444445	기타 오류

인앱 구매 차단 문구

한글	앱 내 구입 기능이 차단이 되어 구매가 불가합니다. 해제 후 다시 시도해 주세요. (설정 > 스크린 타임 > 콘텐츠 및 개인 정보 보호 제한 > iTunes 및 App Store 구입 > 앱 내 구입)
영문	You can’t make a purchase because the in-app purchase feature has been blocked. Please unblock the feature and try again. (Settings > Screen Time > Content & Privacy Restrictions > iTunes & App Store Purchases > In-app Purchases)
프랑스어	u ne peux pas effectuer l’achat car la fonction d’achat in-app a été bloquée. Débloque d’abord la fonction et essaie de nouveau. (Réglages > Temps d’écran > Restrictions relatives au contenu et à la confidentialité > Achats dans l’iTunes et l’App Store > Achats intégrés)
독일어	Kauf nicht möglich, weil das In-App-Kauf-Feature gesperrt ist. Bitte entsperre es und versuche es erneut. (Einstellungen > Bildschirmzeit > Beschränkungen > Käufe im iTunes & App Store > In-App-Käufe)
일본어	App内の購入機能が制限されており、購入できません。解除した後、再度お試しください。 (設定 > スクリーンタイム > コンテンツとプライバシーの制限 > iTunesおよびApp Storeでの購入 > App内課金)
중국어(간체)	因App内购功能已关闭，无法进行购买。请开启后再试。（设置 > 屏幕使用时间 > 内容和隐私访问限制 > iTunes Store 与 App Store 购买项目 > App 内购买项目）
중국어(번체)	因App內購功能已關閉, 無法進行購買. 請開啟後重新再試 (設定 > 螢幕使用時間 > 內容與隱私權限制 > iTunes 與 App Store 購買 > App 內購買)
러시아어	Покупка недоступна, т.к. на устройстве отключены встроенные покупки. Активируйте данную функцию и повторите попытку. (Настройки > Экранное время > Контент и конфиденциальность > Покупки в iTunes Store и App Store > Встроенные покупки)
스페인어	No se puede realizar la compra porque la función de Compras en la app ha sido bloqueada. Favor de desbloquear la función y volver a intentar. (Ajustes > Tiempo de uso > Restricciones de contenido y privacidad > Compras en iTunes y App Store > Compras dentro de la app)
포르투갈어	Você não pode efetuar uma compra porque a função de compra do app foi bloqueada. Por favor, desbloqueie a função e tente novamente. (Definições > Tempo de ecrã > Conteúdo e privacidade > Compras na iTunes e App Store > Compras integradas)
인도네시아어	Pembelian tidak bisa dilakukan karena fitur pembelian In-App telah dibatasi. Silakan matikan pembatasan dan coba lagi. (Pengaturan > Durasi Layar > Pembatasan Konten & Privasi > Pembelian iTunes & App Store > Pembelian In-app)
터키어	Uygulama içi satın alma özelliği bloke edildiği için satın almayı yapamazsınız. Lütfen özelliğin blokajını kaldırıp tekrar deneyiniz. (Ayarlar > Ekran Süresi > İçerik ve Gizlilik Sınırlamaları > iTunes ve App Store Satın Alımları > Uygulama İçi Satın Alım)
베트남어	Bạn không thể thực hiện giao dịch do tính năng Mua In-App đang bị tắt. Vui lòng bật tính năng và thử lại. (Cài đặt > Thời gian sử dụng > Bật giới hạn > Mua hàng iTunes & App Store > Mua In-app)
태국어	คุณไม่สามารถซื้อได้เนื่องจากเมนูการซื้อของในแอพพลิเคชั่นถูกบล็อคอยู่ กรุณาปลดล็อคแล้วลองอีกครั้ง (การตั้งค่า > เวลาหน้าจอ > จำกัดเนื้อหาและความเป็นส่วนตัว > สินค้าที่ซื้อใน iTunes & App Store > การซื้อภายในแอพ)
이탈리아어	Non puoi effettuare l’acquisto perché la funzione di acquisti in-app è bloccata. Preghiamo di sbloccare la funzione e riprovare. (Impostazioni > Tempo di utilizzo > Contenuti e privacy > Acquisti su iTunes e App Store > Acquisti in-app)
아랍어	.لا يمكنك إجراء عملية شراء لأن ميزة الشراء داخل التطبيق قد تم حظرها .الرجاء إلغاء حظر الميزة والمحاولة مرة أخرى (الإعدادات > مدة استخدام الجهاز > قيود المحتوى والخصوصية > الشراء من iTunes Store و App Store > الشراء من داخل التطبيق)