상품 목록 조회

게임 내 상점 진입 시 상품 목록 조회 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 할인 전 가격 문자열 Android
    originalPrice long 할인 전 가격 Android
    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

Cocos2d-x

API Reference: C2SModuleInappV4_ItemInfo

iOS

API Reference: C2SModule.InappV4 ItemInfo

상품 구매

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 할인 전 가격 문자열 Android
    originalPrice long 할인 전 가격 Android
    iconUrl string 상품 아이콘 (512*512) Android
    coinsReward int Amazon 코인 획득 금액
    Amazon에서만 사용
    Android

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

Unity®

API Reference: C2SModule.InappV4.Purchase

Cocos2d-x

API Reference: C2SModuleInappV4_Purchase

iOS

API Reference: C2SModuleInappV4 Purchase

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 > الشراء من داخل التطبيق)