Ungiven Item Receipts

Sending items is occasionally failed or cancelled after purchase. To prevent this situation, request receipt information of items not given by calling restore() method of IAPV4 class.

  • If SUCCESS is returned and ReceiptList is sent after calling restore(), items needed restore exist. Send the ungiven items and complete the restore process.
  • If SUCCESS is not returned after calling restore(), no more process is required for game studio.
  • If calling restore() method occurs errors, notify only some errors required to recognize and skip others for user to keep playing your game.

Followings are sample codes to request receipt information of items not given.

Unity®

API Reference: hive .IAPV4.restore

C++

API Reference: IAPV4 ::restore

Kotlin

API Reference: IAPV4.restore

Java

API Reference: com.hive.IAPV4.restore

Swift

API Reference: IAPV4Interface .restore

Objective-C

API Reference: HIVEIAPV4::restore

 

List of Purchase-restoring Error Codes
Error Code Description
NEED_INITIALIZE Unable to initialize
NETWORK Network error
NOT_SUPPORTED Unable to restore (In-app purchase denied on device, etc.). User sets unavailable store
INVALID_SESSION Invalid session to restore
IN_PROGRESS Restore API in progress
RESTORE_NOT_OWNED No item to restore
NOT_OWNED No item to restore
RESPONSE_FAIL Hive IAP Server error

Verifying Purchase Receipt

Before sending items from game server, verification API from Hive IAP should confirm whether the receipt is valid.
hiveiap_transaction_id in verification API is a unique ID issued by receipt. Thus, save the ID on game server to check duplicated receipts.
If you use verification API and then send all data from Request parameter, Hive IAP Server forwards game data to analyze sales status. Just utilize APIs to search payment on Hive One > Search All as well.
For more details, refer to Hive IAP Receipt Verification API.

Completion to Give Purchased or Ungiven Items

If the game server sends items after purchase, make sure to call transactionFinish() method of IAPV4 class to complete the purchase.

Followings are sample codes which complete a request for item sending.

Unity®

API Reference: hive .IAPV4.transactionFinish

C++

API Reference: IAPV4 ::transactionFinish

Kotlin

API Reference: IAPV4.transactionFinish

Java

API Reference: com.hive.IAPV4.transactionFinish

Swift

API Reference: IAPV4Interface.transactionFinish

Objective-C

API Reference: HIVEIAPV4::transactionFinish:handler:

Followings are sample codes to request to send several items.

Unity®

API Reference: hive .IAPV4.transactionMultiFinish

C++

API Reference: IAPV4 ::transactionMultiFinish

Kotlin

API Reference: IAPV4.transactionMultiFinish

Java

API Reference: com.hive.IAPV4.transactionMultiFinish

Swift

API Reference: IAPV4Interface.transactionMultiFinish

Objective-C

API Reference: HIVEIAPV4::transactionMultiFinish

Get user purchase activity information: using AccountUuid

There may be users who abuse the payment system, such as a single game account using multiple app store accounts to make payments. On the game studio side, you can obtain and analyze specific user behavior by comparing payment user information (AccountUuid).

The method below returns AccountUuid, which is the hash value of PlayerId in UUID v3 format that Hive SDK passes to the app store.

Unity®

API Reference: IAPV4.getAccountUuid

C++

API Reference: IAPV4 ::getAccountUuid

Kotlin

API Reference: IAPV4.getAccountUuid

Java

API Reference: IAPV4.INSTANCE .getAccountUuid

Swift

API Reference: IAPV4Interface.getAccountUuid

Objective-C

API Reference: [HIVEIAPV4 getAccountUuid ]

The game studio can use this hash value with the purchase receipt information to analyze a user’s purchases. The example below shows analyzing the purchase activity of a game account with a specific PlayerId via AccountUuid when there are multiple in-game characters in this game account. This example is only for development reference and does not guarantee the actual operation. 

Store Purchase Meta Info in Game Server In Advance

Before a request to purchase occurs, save the purchase meta information (AccountUuid and character information) to the game server.

 

Send bypassInfo

When a purchase request occurs, send the bypassInfo data to the game server. The code below is pseudo code for development reference.

 

Request for Receipt Verification

The game server passes the bypassInfo data to the Hive IAP v4 server and requests validating the receipt. For details of requesting receipt verification, see here.
The AccountUuid included in the hiveiap_receipt, which is the original receipt of app market/store received within the response value.

 

Analyze by matching AccountUuid of the purchase meta information with AccountUuid of the hiveiap_receipt

Find the user information necessary for analysis, such as the game character information, by matching the AccountUuid previously stored in the purchase meta information with the AccountUuid obtained from the result of the receipt verification. You can analyze the purchase activity of the corresponding game account by matching the purchase meta information with the receipt information.

If a user has purchased multiple items, each purchase can be identified by matching the purchase meta information with the purchaseTime of hiveiap_receipt. For details on hiveiap_receipt, see Verify Receipt and check the API response by market.

Get user purchase activity information: using iadPayload

When requesting a purchase with Purchase() if your game company also provides the predefined data to analyze user purchase activity, the iapPayload, the Hive server matches the purchase receipt corresponding to iapPayload and sends this to the game server. The game company can use the information in the receipt and the information in iadPayload together to analyze user purchase activity.

Define iapPayload and execute Purchase()

When executing each product purchase request, define desired fields and values in iapPayload and use it as an argument. The process is similar to defining purchase metadata.

Request the receipt verification, and receive the iapPayload and the corresponding receipt.

When a payment was completed and the receipt verification is requested, the Hive server matches the iapPayload with its corresponding receipt by purchase and delivered them to the game server. The game studios can use the information in the iapPayload and the receipt to analyze user purchase activity.