View product list and purchase

Searching product list¶

Call the Product List Search API when user enters the in-app store. If user requests a product list, return the IAPV4Product class with the product information.

Product list and details¶

displayPrice¶

• Send displayPrice with the combination of currency sign and price in order (e.g. $0.99). As Android or iOS has its own display type, the order of currency sign and price may show up differently in several countries depending on the OS.
• Make sure to output the currency sign of each country as the same with its table. Refer to the Identifier Policy to confirm the table of currency sign.
• In case of additional countries to add or change VAT, server calculates VAT of all currency and adds to displayPrice, price, displayOriginalPrice andoriginalPrice. Therefore, you have no more work relevant to VAT.

To search the product list, call getProductInfo() method in the IAPV4 class to receive the product information of the list and Lebi balance.
Followings are sample codes to request a search for product list.

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()) {
                // call successful
        }
}));

#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    
         }    
}];

Product purchase¶

Call purchase() method in the IAPV4 class with Market PID, a parameter registered on Apple App Store and Google Play Store, to request product purchase on IAP v4.

Followings are sample codes to request product 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()) {
                //TODO: Request verification of receipt with received receipt
        }
}));

#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
    }
}];

Use iapPayload¶

When executing the purchase (purchase()) or subscription (purchaseSubscription) method, game companies can pass iapPayload as an argument. iapPayload is purchase metadata defined by the game company. For example, when a user purchases a product, it may include the purchase time, purchase user information, purchased game character information, purchased quantity (consumable item), purchase token, etc.

If iapPayload is passed as an argument, the IAP server will verify the purchase receipt, matches this iapPayload value to which the purchase receipt it corresponds to and informs the game server. Specifically, the iapPayload value and the hiveiap_transaction_id value corresponding to the unique receipt key are matched and transmitted to the game server.

Utilizing the purchase receipt and iapPayload pair can solve many problems. For example, there may be a situation where an error occurred when a user purchased an item, and the payment was completed but the item was not delivered. At this time, if restore() method is executed, you can get the purchase receipt for that item. But, as this receipt does not contain information about what type of the item, what time the item was purchased, and what character purchased this item, so it is difficult to know exactly which item the game company should restore for the user. However, this information can be known through the iapPayload paired with the purchase receipt, so that the user can be provided with the item.

Set purchase quantity of consumable items¶

The Google Play Store allows users to purchase two or more of the same in-app products in a single transaction by specifying the quantity in the shopping cart. If your Google Play Console product settings allow multi-quantity purchases, your app should handle multi-quantity purchases and deliver items based on the specified purchase quantity. However, multi-quantity purchases are for consumable in-app products, which are the products that can be purchased again after consumption. Do not enable this feature for the products that cannot be purchased repeatedly.

Precautions before calling purchase() method¶

• If RESPONSE_FAIL or CANCELED error is sent while calling purchase() method due to market issues, notify the problems to users that purchase process occurs errors.
• If users are notified of the purchase problems due to market issues, call restore() method to restore the purchase.
• If NEED_RESTORE error is sent while calling purchase() method, purchase is cancelled. To restore the purchase, call restore() method.
• In case the billing system attempts to pay offline or a child asks his or her parents to pay on behalf of him/her while calling purchase() method, ITEM_PENDING error is sent and the item becomes pending state. The proxy purchase of the parents is supported for the Google Play Store, Amazon and Apple App Store market.
• If succeeded in offline payment or parents' payment instead of their child is made, IAP_UPDATED event is sent through UserEngagement. When the parameter is returned via the UserEngagement eventEnd callback, call restoreSubscription() if the type is "subscription," or call restore() if the type is empty. The completed receipt is available to check by calling these methods.
• To troubleshoot the NOT_SUPPORTED error which notifies unavailable purchase, refer to the Guide for Phrases to Restrict In-app Purchase.
• When purchasing through HIVESTORE in a desktop environment, the payment request screen is displayed in a new window.

Calling hive.IAPV4.purchase(marketPid, null, onIAPV4PurchaseCB); will immediately return a response with ErrorCode:IAPSUCCESS=90 and Code:IAPV4HiveStoreSuccess=-6110000 without receipt information, through onIAPV4PurchaseCB. Based on the ErrorCode (or Code), it is possible to display a guidance message about the state of item distribution eligibility.

• For Windows apps on Google Play (Hive SDK v4 Unity Windows 23.0.0 or higher) using the GOOGLE\_PLAYSTORE market, if the authentication information of the Google account used for payment expires, Hive SDK automatically executes the re-authentication process.
• For Windows apps on Google Play (Hive SDK v4 Unity Windows 23.0.0 or higher) using the GOOGLE\_PLAYSTORE market, when a user presses the confirm button on the payment waiting popup displayed in the app, and the completion of payment is unconfirmed, a response with ErrorCode:IAPSUCCESS=90 and Code:IAPV4PendingPurchase=-6100013 is returned via onIAPV4PurchaseCB. This response does not indicate a failed payment, but rather that the completion of payment could not be confirmed due to an internal error, or the user just did not make a payment. In this case, no receipt is returned, and if the user has completed the payment in the payment browser window, the receipt can be obtained through IAPV4.restore.

Purchase error codes¶

Phrases to restrict in-app purchase¶

Phrases to notify purchase withdrawal policy¶

In accordance with the Content Industry Promotion Act, please expose the notices about withdrawal of purchase and a link to your purchase withdrawal policy on your game stores. For iOS, if the notices about purchase withdrawal were exposed during Apple's inspection process on your app, it could be a reason for the rejection of reviewing your game.