InAppV4 API 레퍼런스 가이드

상수 및 자료형

Market Id

* iOS Native, C Plugin const static int MARKET_LIST_NOT_SELECTED = 0; const static int MARKET_LIST_APPLE_APPSTORE = 1; const static int MARKET_LIST_GOOGLE_PLAYSTORE = 2; const static int MARKET_LIST_HIVE_LEBI = 3; const static int MARKET_LIST_ONESTORE = 4; const static int MARKET_LIST_AMAZON_APPSTORE = 5; const static int MARKET_LIST_SAMSUNG_GALAXYSTORE = 6; const static int MARKET_LIST_HUAWEI_APPGALLERY = 7; const static int MARKET_LIST_FACEBOOK_CLOUD_GAME = 14;   const static int MARKET_LIST_HIVESTORE = 15; MarketListCB 콜백에서 marketList(Array)로 받을 수 있습니다. * Unity Plugin(C#) : 구조체 없이 콜백 메세지(JSON String) 내 marketList key로 존재(Array)

IapV4Lifecycle Type

* iOS Native, C Plugin const static int IAPV4_LIFE_CYCLE_ON_SETUP_FINISHED = 0; const static int IAPV4_LIFE_CYCLE_ON_INITIALIZE_FINISHED = 1; const static int IAPV4_LIFE_CYCLE_ON_SIGN_IN = 2; const static int IAPV4_LIFE_CYCLE_ON_SIGN_OUT = 3; const static int IAPV4_LIFE_CYCLE_ON_PROCESS_URI = 4; const static int IAPV4_LIFE_CYCLE_ON_RESET = 5; IapV4LifecycleCB 콜백에서 type로 받을 수 있습니다. * Unity Plugin(C#) : 구조체 없이 콜백 메세지(JSON String) 내 type key로 존재.

struct CS_IapV4Result

* iOS Native, C Plugin typedef struct CS_IapV4Result {    int result;    int errorCode;    const char* errorMessage; } CS_IapV4Result; result : 에러코드 (항상 존재) errorCode : 에러코드에 대한 상세 분류 (마켓에 따라 비어있을 수 있음) errorMessage : 에러에 대한 문자열 내용 (마켓에 따라 비어있을 수 있음) * Unity Plugin(C#) : 구조체 없이 콜백 메세지(JSON String) 내 iapResult key로 존재. (IapV4LifecycleCB 에는 포함되지 않음)

struct CS_IapV4ProductInfo

* iOS Native, C Plugin typedef struct CS_IapV4ProductInfo {    const char* productType;    const char* marketPid;    const char* currency;    double price;    const char* displayPrice;           //    const char* title;    const char* description;    const char* originalJson;    const char* displayOriginalPrice;    double originalPrice;            //    const char* iconUrl;    int coinsReward; } CS_IapV4ProductInfo; - productType : 아이템 타입(소모성: consumable / 구독형: subscription) - marketPid : 아이템 ID (PID) - currency : 통화 코드 통화 코드는 ISO-4217 입니다. ex) USD 미국, 영국, 일본, 프랑스등의 주요 국가는 통화 코드를 게임의 UI에서 $(USD), ¥(JPY), £(GBP) 등으로 변환해주시고, 나머지 국가는 통화 코드 그대로 노출하시면 됩니다. - price : 실제 가격 - displayPrice : 실제로 보이는 가격 ex) $0.99 통화 기호와 가격을 조합한 형태(예. $0.99)로 displayPrice를 전달합니다. Android와 iOS의 노출 방식이 다르기 때문에 일부 국가에서는 OS에 따라 통화 기호와 가격 순서가 다를 수 있습니다. 각 나라의 통화기호는 통화기호표와 동일하게 출력합니다. 통화기호는 HIVE 식별자 정책(https://developers.withhive.com/dev4/basics/identifier/#currency)을 참고하세요. 다른 나라에서 부가세를 추가하거나 변동하는 경우에 서버에서 계산하여 displayPrice, price, displayOriginalPrice, originalPrice에 반영하므로 추가 작업이 필요 없습니다. - title : 아이템 이름 - description : 아이템 부가 설명 - originalJson : 마켓에서 전달받은 응답 - displayOriginalPrice : 마켓에서 전달받은 표기 가격 - originalPrice : 마켓에서 전달받은 가격 Google은 price 값과 originalPrice 값이 다르면 할인 전 원가를 표기할 수 있습니다. 두 값이 같다면 할인 상태가 아님을 의미합니다. - iconUrl : 아이템 아이콘 이미지 url - coinsReward : 아마존 코인 보상 가격   ProductInfoCB 콜백에서 productInfo(Array)로 받을 수 있습니다. 에러 상황에선 내부 멤버가 null, 혹은 빈스트링("") 처리됩니다. * Unity Plugin(C#) : 구조체 없이 콜백 메세지(JSON String) 내 productInfo key로 존재(Array). // Unity CS_IapV4GetProductInfo 콜백 응답 예 {     "iapResult":     {         "result":0,         "errorCode":0,         "errorMessage":""      },     "numOfProduct":1,     "productInfo":     [         {             "productType":"",             "marketPid":"",             "currency":"",             "price":0,             "displayPrice":"",             "title":"",             "description":"",             "originalJson":"",             "displayOriginalPrice":"",             "originalPrice":0,             "iconUrl":"",             "coinsReward":0         }     ] }

struct CS_IapV4ReceiptInfo

* iOS Native, C Plugin typedef struct CS_IapV4ReceiptInfo {    int type;    const char* iapPayload; // 구 additionalInfo    const char* bypassInfo;    const char* hiveiapReceipt;    // ProductInfo    const char* productType;    const char* marketPid;    const char* currency;    double price;    const char* displayPrice;           //    const char* title;    const char* description;    const char* originalJson;    const char* displayOriginalPrice;    double originalPrice;            //    const char* iconUrl;     int coinsReward; } CS_IapV4ReceiptInfo; - type : marketId (Market Id) - iapPayload : 구매시 입력한 추가 정보 - bypassInfo : HIVE 영수증 검증 시 사용하는 암호화 데이터. - hiveiapReceipt: 구매 영수증 이하 struct CS_IapV4ProductInfo와 동일 ReceiptInfoCB 콜백에서 receiptInfo로 받을 수 있습니다. ReceiptListInfoCB 콜백에서 receiptInfo(Array)로 받을 수 있습니다. 에러 상황에선 내부 멤버가 null, 혹은 빈스트링("") 처리됩니다. * Unity Plugin(C#) : 구조체 없이 콜백 메세지(JSON String) 내 receiptInfo key로 존재. // Unity CS_IapV4Purchase, CS_IapV4PurchaseSubscription 콜백 응답 예 {     "iapResult":     {         "result":0,         "errorCode":0,         "errorMessage":""      },     "receiptInfo":     {         "type":0,         "iapPayload":"",  // 구 additionalInfo         "bypassInfo":"",         "hiveiapReceipt":"",         "productType":"",         "marketPid":"",         "currency":"",         "price":0,         "displayPrice":"",         "title":"",         "description":"",         "originalJson":"",         "displayOriginalPrice":"",         "originalPrice":0,         "iconUrl":"",         "coinsReward":0     } } // Unity CS_IapV4Restore, CS_IapV4RestoreSubscription 콜백 응답 예 {     "iapResult":     {         "result":0,         "errorCode":0,         "errorMessage":""     },     "numOfReceipt":2,     "receiptInfo":     [         {             "type":0,             "iapPayload":"",  // 구 additionalInfo             "bypassInfo":"",             "hiveiapReceipt":"",             "productType":"",             "marketPid":"",             "currency":"",             "price":0,             "displayPrice":"",             "title":"",             "description":"",             "originalJson":"",             "displayOriginalPrice":"",             "originalPrice":0,             "iconUrl":"",             "coinsReward":0         },         {             "type":0,             "iapPayload":"",  // 구 additionalInfo             "bypassInfo":"",             "hiveiapReceipt":"",             "productType":"",             "marketPid":"",             "currency":"",             "price":0,             "displayPrice":"",             "title":"",             "description":"",             "originalJson":"",             "displayOriginalPrice":"",             "originalPrice":0,             "iconUrl":"",             "coinsReward":0         }     ]     }

콜백 함수

void MarketListCB(CS_IapV4Result iapResult, int numOfMarketList, int* marketList)

• Description

  게임 클라이언트에서 이용 가능한 마켓 정보를 결과값으로 반환.

해당 콜백을 지원하는 마켓은 Apple, GooglePlay, Lebi, OneStore, Amazon, Huawei AppGallery 가 있습니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	CS_IapV4Result	iapResult	호출 결과 값
in	int	numOfMarketList	이용 가능한 마켓의 갯수 (마켓이 없거나 에러상황일 땐 0)
in	int*	marketList	이용 가능한 마켓 정보 (Market Id) - struct CS_IapV4Result, Market Id 부분을 참고해 주세요. - Unity plugin : Param Name을 key 값으로 하는 Json String 형식. (CS_IapV4MarketConnectUnity 설명에서 자세히)

• Remark

  not comment

void ProductInfoCB(CS_IapV4Result iapResult, int numOfProduct, CS_IapV4ProductInfo* productInfo)

• Description

  결과값으로 상품 목록의 상품 정보, 러비 잔액을 전달 받습니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	CS_IapV4Result	iapResult	호출 결과 값
in	int	numOfProduct	상품의 갯수 (상품이 없거나 에러상황일 땐 0)
in	CS_IapV4ProductInfo*	productInfo	상품 정보 (존재하지 않는다면 null) - struct CS_IapV4Result, CS_IapV4ProductInfo 부분을 참고해 주세요. - Unity plugin : Param Name을 key 값으로 하는 Json String 형식. (CS_IapV4ProductInfoUnity 설명에서 자세히)

• Remark

  not comment

void ReceiptInfoCB(CS_IapV4Result iapResult, CS_IapV4ReceiptInfo receiptInfo)

• Description

  구매 성공시 영수증과 상품 데이터를 전달합니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	CS_IapV4Result	iapResult	호출 결과 값
in	CS_IapV4ReceiptInfo	receiptInfo	영수증 정보 (에러 상황에선 내부 멤버가 null) - struct CS_IapV4Result, CS_IapV4ReceiptInfo 부분을 참고해 주세요. - Unity plugin : Param Name을 key 값으로 하는 Json String 형식. (CS_IapV4PurchaseUnity 및 CS_IapV4PurchaseSubscriptionUnity 설명에서 자세히)

• Remark

  not comment

void ReceiptListInfoCB(CS_IapV4Result iapResult, int numOfReceipt, CS_IapV4ReceiptInfo* receiptInfo)

• Description

  restore 시 현재 transaction 종료되지 않은 영수증과 상품 데이터를 전달합니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	CS_IapV4Result	iapResult	호출 결과 값
in	int	numOfReceipt	미완료 된 구매 영수증의 갯수 (미완료 된 구매상황이 없거나 에러상황일 땐 0)
in	CS_IapV4ReceiptInfo*	receiptInfo	영수증 정보 (미완료 된 구매상황이 없거나 에러상황일 땐 null) - struct CS_IapV4Result, CS_IapV4ReceiptInfo 부분을 참고해 주세요. - Unity plugin : Param Name을 key 값으로 하는 Json String 형식. (CS_IapV4RestoreUnity 및 CS_IapV4RestoreSubscriptionUnity 설명에서 자세히)

• Remark

  not comment

void TransactionCB(CS_IapV4Result iapResult, const char* marketPid)

• Description

  finish 완료 시 전달받는 결과 값

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	CS_IapV4Result	iapResult	호출 결과 값
in	const char*	marketPid	finish 완료된 marketPid - struct CS_IapV4Result 부분을 참고해 주세요. - Unity plugin : Param Name을 key 값으로 하는 Json String 형식. (CS_IapV4TransactionFinishUnity 설명에서 자세히)

• Remark

  not comment

void BalanceCB(CS_IapV4Result iapResult, int balance)

• Description

  러비 충전을 완료한 후 잔액을 확인할 수 있습니다. (Android Only)

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	CS_IapV4Result	iapResult	호출 결과 값
in	int	balance	러비 잔액 - struct CS_IapV4Result 부분을 참고해 주세요. - Unity plugin : Param Name을 key 값으로 하는 Json String 형식. (CS_IapV4GetBalanceUnity 설명에서 자세히) (Android Only)

• Remark

  not comment

void CheckPromotePurchaseCB(CS_IapV4Result iapResult, const char* marketPid)

• Description

  App Store에서 구매 요청이 들어온 마켓 PID 값을 반환받을 수 있습니다. (iOS Only)

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	CS_IapV4Result	iapResult	호출 결과 값
in	const char*	marketPid	finish 완료된 marketPid - struct CS_IapV4Result 부분을 참고해 주세요. - Unity plugin : Param Name을 key 값으로 하는 Json String 형식. (CS_IapV4CheckPromotePurchaseUnity 설명에서 자세히) (iOS Only)

• Remark

  not comment

void IapV4LifecycleCB(int type, const char* data)

• Description

  Android 구글에서 오프라인 구매 시 구글로부터 구매 완료 신호를 받습니다.

  Android, iOS에서 앱 런타임 중 미성년자의 결제 요청을 부모가 승인하여 트랜잭션의 상태가 구매 보류(Pending) 상태에서 구매 완료 상태로 변경되면 신호를 받습니다. CS_IapV4MarketConnect 메서드 호출 이전이나 호출 직후 호출하여 콜백 핸들러를 미리 등록 해야 합니다.

  소모성 상품에 대하여 구매 트랜직션이 구매 완료 상태로 변경될 경우 첫 번째 파라미터 type은 4(IAPV4_LIFE_CYCLE_ON_PROCESS_URI), 두 번째 파라미터는 문자열 "interwork://hive/iapupdated"이 전달됩니다.

  구독형 상품에 대하여 구매 트랜잭션이 구매 완료 상태로 변경될 경우 첫 번째 파라미터 type은 4(IAPV4_LIFE_CYCLE_ON_PROCESS_URI), 두 번째 파라미터는 문자열 "interwork://hive/iapupdated/subscription"이 전달됩니다.

  구매 완료 신호를 전달 받으면 두 번째 파라미터 값을 통해 상품 유형에 따라 CS_IapV4Restore 또는 CS_IapV4RestoreSubscription 메서드를 호출하여 영수증 정보를 획득하고 구매 복구를 진행 하시면 됩니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	int	type
in	const char*	data	- IapV4Lifecycle Type 부분을 참고해 주세요. - Unity plugin : Param Name을 key 값으로 하는 Json String 형식. (CS_IapV4SetLifecycleCBUnity 설명에서 자세히)

• Remark

  not comment

void InAppOfferCB(int responseCode)

• Description

  게임 혜택 유도 팝업 요청 결과를 받습니다. (Android Only)

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	int	responseCode	응답 결과가 2인 경우 혜택 유도에 대한 처리 필요. 그 외의 경우 별도 처리가 필요 없음. - 2 : 유저가 혜택 제안을 확인하고 사용하기를 수락한 상황, 유저가 구매할 인앱 항목을 선택할 수 있게 앱 내 상점 페이지 등으로 이동 처리 필요

• Remark

  not comment

콜백 함수 (Unity)

Unity 콜백 함수 사용 예

함수

void CS_IapV4MarketConnect(MarketListCB cb)

• Description

  IAP v4 초기화 함수.

  HIVE IAP v4를 사용하기 위해서는 구매 전 한번 IAP 초기화를 요청해야 합니다. IAP 초기화를 요청하면 게임 클라이언트에서 이용 가능한 마켓 정보를 결과값으로 반환합니다. 마켓 정보는 Market Id로 정의되어 있습니다.

  마켓에서 게임 서비스를 종료하더라도 기존 유저가 게임 플레이를 지속하려면 게임 내 재화 상점에 접근할 수 있어야 합니다. 이를 위해 게임 스튜디오에서는 현금 결제 상점과 게임 내 재화 상점을 반드시 분리해 설계해야 합니다. IAP v4 초기화로 전달되는 결과값은 게임 내 상점에 접근하는 용도가 아니니 목적과 다르게 사용하지 마세요.

  인앱초기화가 성공하면 MarketListCB 콜백이 호출 됩니다.

  MarketListCB의 numOfMarketList 0이거나 콜백을 받지 못하면 모든 구매가 실패로 처리됩니다.

  CS_IapV4MarketConnect() 호출 결과가 실패로 왔을 경우 상품 목록 조회나 구매 기능이 정상적으로 진행되지 않습니다.

  실패 errorCode를 받았을 경우 게임클라이언트에서 자체 구현을 통해 ‘성공 콜백을 받을 때까지 재시도’, ‘에러 상황(마켓 사용 불가)을 팝업으로 사용자에게 노출' 등으로 대응이 필요합니다.

  CS_IapV4MarketConnect() 실패는 ‘단말에 계정 로그인이 정상 여부', ‘Google Playstore, Apple Appstore 등 각 마켓 플랫폼 앱에 로그인 정상 여부’, ‘Hive Console에 앱아이디에 따른 마켓 설정 정상 여부' 등이 원인이 될 수 있습니다.

  MarketList 콜백에서 전달된 errorCode는 Unity 플러그인 환경인 경우 패키지에 첨부된 C2SResultAPI.cs 파일에서, C 플러그인 환경인 경우 C2SResultAPI.h 에서 확인하실 수 있습니다.

  해당 ResultAPI코드를 확인하여 성공(errorCode=0)이 아닌 경우 대응 및 문의바랍니다.
  
  - HiveLebi 설명 : https://developers.withhive.com/ko/dev4/billing/lebi/

  - HiveStore (Hive PG) 설명 : https://developers.withhive.com/ko/dev4/billing/pg-billing/

초기화 실패하는 경우는 아래와 같습니다.

• AppStore나 PlayStore가 점검 중으로 item 정보를 못 받음.
• AppStore, PlayStore Test 계정이 아님.
• iOS 경우 Test 단말로 등록되지 않았음.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	MarketListCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4MarketConnectUnity(string unityCBObjName, string unityCBFuncName)

void CS_IapV4GetProductInfo(ProductInfoCB cb)

• Description

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

  해당 함수는 소모성 상품 목록 조회 API입니다.

  CS_IapV4GetProductInfo() 호출 결과가 실패로 왔을 경우 상품 페이지 구현에 소모성 아이템 정보를 활용할 수 없습니다.

  실패 errorCode를 받았을 경우 게임클라이언트에서 자체 구현을 통해 ‘성공 콜백을 받을 때까지 재시도’, ‘에러 상황(마켓 사용 불가)을 팝업으로 사용자에게 노출' 등으로 대응이 필요합니다.

  ProductInfo 콜백에서 전달된 errorCode는 Unity 플러그인 환경인 경우 패키지에 첨부된 C2SResultAPI.cs 파일에서, C 플러그인 환경인 경우 C2SResultAPI.h 에서 확인하실 수 있습니다.

  해당 ResultAPI코드를 확인하여 성공(errorCode=0)이 아닌 경우 대응 및 문의바랍니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	ProductInfoCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4GetProductInfoUnity(string unityCBObjName, string unityCBFuncName)

void CS_IapV4GetSubscriptionProductInfo(ProductInfoCB cb)

• Description

  게임 내 구독형 상품 상점에 진입할 때 구독형 상품 목록 조회 API를 호출해야 합니다. 구독형 상품 목록 요청을 수행하면 결과 통지 시 ProductInfoCB 콜백에 상품 목록 정보를 포함하여 반환합니다. ProductInfoCB 콜백에 대한 설명은 상품 목록 조회에서 전달되는 클래스와 동일한 형태입니다.

  해당 함수는 구독형 상품 목록 조회 API입니다.

  CS_IapV4GetSubscriptionProductInfo() 호출 결과가 실패로 왔을 경우 상품 페이지 구현에 구독형 아이템 정보를 활용할 수 없습니다.

  실패 errorCode를 받았을 경우 게임클라이언트에서 자체 구현을 통해 ‘성공 콜백을 받을 때까지 재시도’, ‘에러 상황(마켓 사용 불가)을 팝업으로 사용자에게 노출' 등으로 대응이 필요합니다.

  ProductInfo 콜백에서 전달된 errorCode는 Unity 플러그인 환경인 경우 패키지에 첨부된 C2SResultAPI.cs 파일에서, C 플러그인 환경인 경우 C2SResultAPI.h 에서 확인하실 수 있습니다.

  해당 ResultAPI코드를 확인하여 성공(errorCode=0)이 아닌 경우 대응 및 문의바랍니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	ProductInfoCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4GetSubscriptionProductInfo(const char* unityCBObjName, const char* unityCBFuncName)

void CS_IapV4Purchase(String (const char*) marketPid, String (const char*) iapPayload, ReceiptInfoCB cb)

• Description

  HIVE IAP v4에서 상품 구매는 App Store, Play Store에 등록된 marketPid를 매개변수로 CS_IapV4Purchase 메서드를 호출하여 상품 구매를 요청합니다.

  해당 함수는 소모성 상품 목록 조회 API입니다.

  C2S.21.0 이상 버전부턴 additionalInfo 파라메터 데이터 대신 iapPayload 정보를 추가할 수 있습니다. 해당 API 콜백으로 영수증 정보와 iapPayload 정보를 받을 수 있습니다. 이후 서버 검증 API 응답에서 전달받은 iapPayload를 해석하여 게임앱에서 자체적인 용도로 사용할 수 있습니다. iapPayload 데이터 입력 시 암호화하여 사용함을 권장합니다.

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

• purchase() 메서드를 호출하는 도중 마켓 오류로 RESPONSE_FAIL, CANCELED 에러가 발생하면 사용자에게 구매 과정에 문제가 있음을 알립니다.
• 구매 과정에 문제가 있다는 알림을 사용자가 확인했다면 restore() 메서드를 호출하여 구매 복구를 진행합니다.
• purchase() 메서드를 호출하는 도중 NEED_RESTORE 에러가 발생하면 구매가 취소되며, 이 경우 restore()메서드를 호출하여 구매 복구를 진행합니다.
• Android에서 purchase() 메서드를 호출하는 도중 오프라인 결제를 시도하는 경우 ITEM_PENDING 에러가 발생하며 해당 아이템은 구매 대기 상태가 됩니다.
• Android, iOS에서 purchase() 메소드를 호출하는 도중 미성년자가 부모에게 결제 요청을 진행하는 경우 ITEM_PENDING 에러가 발생하며 해당 아이템은 구매 대기 상태가 됩니다.
• 오프라인 결제에 성공한 경우나 부모가 요청 받은 결제를 승인할 경우, CS_IapV4SetLifecycleCB를 통해 이벤트를 수신하고, restore() 메서드 호출로 결제 완료 상품의 영수증 정보를 확인할 수 있습니다.
• 구매 복구 시 RESPONSE_FAIL 에러가 발생하면 구매를 진행할 수 없으므로 사용자에게 복구 과정에 문제가 있음을 알려야 합니다.
• 인앱 구입 차단 문구 가이드(https://developers.withhive.com/dev4/billing/iapv4-purchase/#inapp_reject_text)를 참고하면 필요에 따라 NOT_SUPPORTED 에러 처리로 사용자가 구매 할 수 없는 상태임을 알릴 수 있습니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	String (const char*)	marketPid	구매할 marketPid
in	String (const char*)	iapPayload	구매 시 전달할 추가 데이터 (구 additionalInfo)
in	ReceiptInfoCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4PurchaseUnity(string marketPid, string iapPayload, string unityCBObjName, string unityCBFuncName)

void CS_IapV4PurchaseSubscription(String (const char*) marketPid, String (const char*) oldMarketPid, String (const char*) iapPayload, ReceiptInfoCB cb)

• Description

  HIVE IAP v4에서 상품 구매는 App Store, Play Store에 등록된 marketPid를 매개변수로 CS_IapV4PurchaseSubscription 메서드를 호출하여 구독형 상품 구매를 요청합니다.

  기존에 구독 중인 상품이 있어 구독 변경이 필요한 경우에는 oldMarketPid에 구독중인 상품의 marketPid를 입력하세요. 이 기능은 Android에서만 동작합니다.

  해당 함수는 구독형 상품 목록 조회 API입니다.

  C2S.21.0 이상 버전부턴 additionalInfo 파라메터 데이터 대신 iapPayload 정보를 추가할 수 있습니다. 해당 API 콜백으로 영수증 정보와 iapPayload 정보를 받을 수 있습니다. 이후 서버 검증 API 응답에서 전달받은 iapPayload를 해석하여 게임앱에서 자체적인 용도로 사용할 수 있습니다. iapPayload 데이터 입력 시 암호화하여 사용함을 권장합니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	String (const char*)	marketPid	구매할 marketPid
in	String (const char*)	oldMarketPid	구독중인 상품의 marketPid (구독 변경 시)
in	String (const char*)	iapPayload	구매 시 전달할 추가 데이터 (구 additionalInfo)
in	ReceiptInfoCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4PurchaseSubscriptionUnity(string marketPid, string oldMarketPid, string iapPayload, string unityCBObjName, string unityCBFuncName)

void CS_IapV4Restore(ReceiptListInfoCB cb)

• Description

  상품 구매 과정에서 여러가지 상황으로 인하여 아이템 지급을 실패하거나 취소되는 경우가 발생할 수 있습니다. 이런 상황을 대비하기 위해서는 미 지급된 아이템의 영수증 정보를 요청해야 합니다. CS_IapV4Restore() 메서드를 호출하여 미 지급된 아이템의 정보를 요청하세요.

  해당 함수는 소모성 상품 목록 조회 API입니다.

  C2S.21.0에서 추가된 iapPayload 정보는 CS_IapV4Restore 콜백으로는 전달되지 않습니다. 서버 검증 API 응답으로 전달된 iapPayload 정보를 활용 바랍니다.

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

• restore() 메서드를 호출한 결과 값이 SUCCESS이고 ReceiptList가 전달된 경우 복구할 아이템이 존재하는 상황입니다. 미 지급된 아이템을 지급하고 완료로 처리하세요.
• restore() 메서드를 호출한 결과 값이 SUCCESS가 아닌 경우 게임에서 처리하지 않아도 됩니다.
• restore() 메서드를 호출 후 에러가 발생할 경우 유저가 반드시 알아야 하는 에러(https://developers.withhive.com/api/hive-api/resultapicode_iapv4/#restore)를 제외하고는 별도 알림 없이 유저가 게임을 계속 플레이할 수 있도록 구현하세요.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	ReceiptListInfoCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4RestoreUnity(string unityCBObjName, string unityCBFuncName)

void CS_IapV4RestoreSubscription(ReceiptListInfoCB cb)

• Description

  구독 중인 상품의 지급이 이루어지지 않았다면 구독 상태를 복구하는 CS_IapV4RestoreSubscription() 메서드를 호출해 이전에 구매한 구독 상품의 영수증을 요청해야 합니다.

  해당 함수는 구독형 상품 목록 조회 API입니다.

  C2S.21.0에서 추가된 iapPayload 정보는 CS_IapV4Restore 콜백으로는 전달되지 않습니다. 서버 검증 API 응답으로 전달된 iapPayload 정보를 활용 바랍니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	ReceiptListInfoCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4RestoreSubscriptionUnity(string unityCBObjName, string unityCBFuncName)

void CS_IapV4TransactionFinish(String (const char*) marketPid, TransactionCB cb)

• Description

  상품 구매 후, 아이템 지급을 완료했다면 CS_IapV4TransactionFinish()를 반드시 호출하여 구매를 완료하세요.

  지급 완료된 상품에 대해 지급 완료 요청을 메서드를 호출하지 않으면, 미지급된 아이템으로 남아있게 되어 restore() 메서드 호출 시 영수증 정보를 반환할 수 있으니 상품 구매 후 모든 프로세스가 완료되었다면 반드시 지급 완료 API를 호출해 주세요.

  결제는 성공했으나 CS_IapV4TransactionFinish() 메서드 호출 결과가 3일 이내 성공하지 못하는 경우 자동 환불됩니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	String (const char*)	marketPid	구매할 marketPid
in	TransactionCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4TransactionFinishUnity(string marketPid, string unityCBObjName, string unityCBFuncName)

void CS_IapV4CheckPromotePurchase(CheckPromotePurchaseCB cb)

• Description

  iOS 11 버전부터 ‘App Store에 노출한 인앱 상품의 인게임 구매 연동’ (이하 Promotional IAP) 기능을 지원합니다. Apple App Store의 상품 페이지 및 검색창에서 게임 내 인앱 상품을 노출할 수 있으며, 최대 20개까지 등록 가능합니다. Promotional IAP로 등록한 상품은 iOS 11 버전 이상에서만 볼 수 있습니다.

  Promotional IAP를 구현하기 위해 HIVE SDK에서는 Apple App Store에서 구매 요청이 들어온 마켓 PID 값을 반환해주는 checkPromotePurchase API를 제공합니다.

  checkPromotePurchase API를 호출하는 시점은 앱 구매가 가능한 시점이어야 합니다. checkPromotePurchase API를 호출하기 전에 게임에서는 초기화(CS_IapV4MarketConnect), 상품 정보 요청(CS_IapV4GetProductInfo), 로그인(CS_IapV4SetUid, C2S.19.6 이상에선 CS_IapV4SetUid 호출 필요 없음) 선행작업을 완료하여 앱 구매 가능한 상태로 호출해주세요.

  한번 전달된 마켓 PID는 재전달되지 않기 때문에, 게임에서는 결과로 반환받은 마켓 PID를 관리해야 합니다.

  해당 함수는 iOS Only API입니다.

Promotional IAP에 대한 자세한 설명은 다음을 참고해주세요.

• Promoting Your In-App Purchases(https://developer.apple.com/app-store/promoting-in-app-purchases/)
• Promoting In-App Purchases Programming Guide(https://developer.apple.com/documentation/storekit?language=objc)

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	CheckPromotePurchaseCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4CheckPromotePurchaseUnity(string unityCBObjName, string unityCBFuncName)

void CS_IapV4SetUid(String(const char*) uid) (Deprecated, C2S.19.6)

• Description

  현재 로그인 중인 계정의 uid를 InAppV4 SDK에 세팅하는 API입니다.

  구매 및 구매 복구를 위해서는 해당 API를 호출하여 반드시 uid를 세팅해주어야합니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	String(const char*)	uid	현재 로그인 중인 계정의 uid

• Remark

  C# : void CS_IapV4SetUid(string uid)

int CS_IapV4GetSelectedMarket()

• Description

  현재 선택된 마켓을 확인할 수 있는 API입니다.

  선택된 마켓이 없다면 NOT_SELECTED를 리턴합니다.

• Return Value

no return value

• Remark

  C# : int CS_IapV4GetSelectedMarket()

void CS_IapV4ShowMarketSelection(MarketListCB cb)

• Description

  구글/러비 마켓을 모두 혼용하는 앱아이디의 경우 해당 API를 호출하여 어떤 마켓을 타겟팅할지 선택하는 API 입니다. API 호출 시 구글/러비를 선택하는 페이지(모듈 제공 페이지)가 노출되며 선택한 마켓에 따라 모듈 내부에 타겟팅 됩니다. 이후 아이템 정보(ProductInfo API)를 호출하면 해당 마켓에 대한 아이템 정보를 얻을 수 있습니다.

  해당 함수는 Android Only API입니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	MarketListCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4ShowMarketSelectionUnity(string unityCBObjName, string unityCBFuncName)

void CS_IapV4GetBalanceInfo(BalanceCB cb)

• Description

  러비 잔액(balance)를 반환 요청하는 API 입니다.

  해당 함수는 Android Only API입니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	BalanceCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4GetBalanceInfoUnity(string unityCBObjName, string unityCBFuncName)

void CS_IapV4ShowCharge(BalanceCB cb)

• Description

  러비 충전 페이지를 호출하는 API 입니다. 해당 과정이 완료되면 현재 러비 잔액(balance)가 콜백으로 전달됩니다.

  해당 함수는 Android Only API입니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	BalanceCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4ShowChargeUnity(string unityCBObjName, string unityCBFuncName)

void CS_IapV4SetLifecycleCB(IapV4LifecycleCB cb)

• Description

  Android 구글에서 오프라인 구매 시 구글로부터 구매 완료 신호를 얻습니다.

  또한 Android, iOS에서 앱 런타임 중 미성년자의 결제 요청을 부모가 승인하여 트랜잭션의 상태가 구매 보류(Pending) 상태에서 구매 완료 상태로 변경되면 신호를 받습니다. CS_IapV4MarketConnect 메서드 호출 이전이나 호출 직후 호출하여 콜백 핸들러를 미리 등록 해야 합니다.

  소모성 상품에 대하여 구매 트랜직션이 구매 완료 상태로 변경될 경우 첫 번째 파라미터 type은 4(IAPV4_LIFE_CYCLE_ON_PROCESS_URI), 두 번째 파라미터는 문자열 "interwork://hive/iapupdated"이 전달됩니다.

  구독형 상품에 대하여 구매 트랜잭션이 구매 완료 상태로 변경될 경우 첫 번째 파라미터 type은 4(IAPV4_LIFE_CYCLE_ON_PROCESS_URI), 두 번째 파라미터는 문자열 "interwork://hive/iapupdated/subscription"이 전달됩니다.

  구매 완료 신호를 전달 받으면 두 번째 파라미터 값을 통해 상품 유형에 따라 CS_IapV4Restore 또는 CS_IapV4RestoreSubscription 메서드를 호출하여 영수증 정보를 획득하고 구매 복구를 진행 하시면 됩니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	IapV4LifecycleCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4SetLifecycleCBUnity(string unityCBObjName, string unityCBFuncName)

const char* CS_IapV4GetVersion()

• Description

  InAppV4 버전 정보를 반환합니다.

• Return Value

const char*

• Remark

  Available in Android InAppV4 4.15.2, iOS InAppV4 4.15.2

  Java : String getVersion()

  C# : string GetVersion()

void CS_IapV4GetMarketProductInfo(const char** pidList, ProductInfoCB cb)

• Description

  마켓 초기화(MarketConnect) 이전에 특정 아이템 혹은 아이템들에 대한 정보를 미리 얻고자하는 경우 해당 API를 사용하여 아이템 정보를 얻습니다.

  Apple 인앱 Tier 변경 이슈와 관련하여 앱 진행중 계정의 국가정보를 변경하여 curreny 정보를 바꾸는 경우 등 앱 실행 초기 아이템 정보와 앱 진행 중간 아이템 정보 간 변경사항을 확인할 수 있도록 지원하기 위한 API 입니다.
  (MarketConnect API 호출 전 미리 해당 API를 호출하여 특정 아이템들에 대해 정보를 미리 받아놓고 사용 가능)

  해당 API는 iOS Apple AppStore 에서만 사용 가능(iOS Only)하며, Android 관련 마켓에서 호출 시 에러(not supported)를 반환합니다. 

  [Important]

  - Apple Developer 콘솔에서 인앱 아이템의 통화(currency)에 따른 가격 정보를 등록할 수 있도록 대응되었습니다.

  - 더이상 해당 API 호출을 통해 통화 변경 여부를 확안하지 않아도 됩니다.

  - 통화에 따른 가격 정보를 등록한 경우 유저의 결제 계정 변경으로 가격 티어(Tier) 관련없이 콘솔에 등록된 국가 통화 가격으로 결제됩니다.

• Return Value

no return value

• Parameter

in/out	Type	Name	Description
in	const char**	pidList	정보 요청할 pid 목록
in	ProductInfoCB	cb	콜백 함수를 등록합니다.

• Remark

  C# : void CS_IapV4GetMarketProductInfoUnity(string[] pidList, string unityCBObjName, string unityCBFuncName)