Skip to main content

In-app purchases

caution

This feature is still experimental. Breaking changes may occur at any time.

How to create product IDs

Please contact your developer relations representative and they will provide the form for requesting product ids for IAP. Link Game Platform team can also create test purchase ids for you, so that you can debug the IAP feature without actual purchases in Google Play.

Where to find an IAP transaction log

You can find purchases and their status in the "In-App Purchases" tab of your game page on the Link Game Developer Console.

How to Properly Handle Errors in In-App Purchase

This article will dig into what kind of errors can occur in In-App Purchase, and propose an approach to achieve fail-safe and recoverability regarding purchase handling in game's implementation.

Assuming the game has implemented the purchase handling according to the suggested flow (Validate => Consume => Provision). There're 3 failure points that need to think about. And this can help categorizing the failed purchases can be either one of the 4 possible scenarios.

Unvalidated purchases

Purchase validation on game's server failed due to network failure or game's internal error.

Strategy:

  1. Retry validation
  2. If retry doesn't go well, fallback to Rescue Plan
  3. If Rescue Plan doesn't work, fallback to Customer Support

Invalid purchases

The signature in the purchase information didn't match. Some one may want to fake about a purchase, or platform failed to provide correct signature due to technical trouble.

Strategy:

  1. Simply reject the purchase payload
  2. If it happens to a platform problem, it will fit into Rescue Plan once platform is recovered from technical trouble

Validated unconsumed purchases

Consumption might fail due to network failure or platform outage.

Strategy:

  1. (Link Game SDK will automatically retry consumption for 3 times if it sees the situation as caused by poor network connection)
  2. If SDK doesn't work, fallback to Rescue Plan
  3. If Rescue Plan doesn't work, fallback to Customer Support

Validated consumed unprovisioned purchases

Provisioning failed due to network failure or game's internal error.

Strategy:

  1. Retry provisioning
  2. If retry doesn't work and you have Provision Rescue Plan, fallback to Provision Rescue Plan
  3. If neither retry nor Provision Rescue Plan work, fallback to Customer Support

Rescue Plan

Rescue plan can help dealing with these 3 cases:

  • Unvalidated purchases
  • Invalid purchases
  • Validated unconsumed purchases

Some time later after the error happens, user may possibly move to a place with better internet connection, or restart the game with a cleaner state, or maybe platform outage or technical trouble is resolved, which could just remove the problem that caused the previous failure. It's recommended to carry out the rescue plan at least once each game play or even more, and it can happen in the background without interruption to the game play. A typical Rescue Plan can be illustrated as:

  1. Choose the trigger of execution (e.g. when shop screen is shown)
  2. When triggered, call LinkGame.getPurchasesAsync()
  3. In the background, resume validation, consumption and provision for all the purchases enlisted

Provision Rescue Plan

Provision Rescue Plan can help dealing with:

  • Validated consumed unprovisioned purchases

The logic is quite same with Rescue Plan, but it specifically deals with provisioning failure, which is something totally relying on the game's implementation. A typical Provision Rescue Plan can be illustrated as:

  1. Choose the trigger of execution (e.g. right after Rescue Plan is executed)
  2. When triggered, call game's API to look up unprovisioned purchases
  3. Resume provisioning all the purchases enlisted

IAP Customer Support Requirement

Customer support is the final stage to help a user to handle a failed purchase. User will receive Google Play order receipt mail for each purchases they made on Link Game Platform, and the "order number" in the receipt will be the unique ID heavily used during IAP troubleshooting. They are projected as "paymentID" in Link Game SDK.

For game developers, it'll be essential to secure these ability to enable proper customer support service:

  • Keep all purchases and knowing their paymentID, validation, consumption, provision status, provision date time
  • A Rescue Plan implemented in game
  • A Provision Rescue Plan implemented in game or something equivalent (e.g. manual way to provision a specific purchase)

Customer Support Scenarios

When receiving user's inquiry with a "order number" attached, CS can follow this reference about how to properly react to the situation:

Unvalidated purchases

By looking up the order number, they can be found on Developer Console, but not in game's transaction data storage.

Strategy:

Instruct the user about how to start rescue plan

Validated unconsumed purchases

By looking up the order number, they can be found on both Developer Console and game's purchase data storage, status is not consumed

Strategy:

Instruct the user about how to start rescue plan

Validated consumed unprovisioned purchases

By looking up the order number, they can be found on both Developer Console and game's purchase data storage, status is consumed but unprovisioned

Strategy:

If you have a provision rescue plan, instruct the user about how to start it. If not, please manually provision the purchase.

Missing purchases

The order number doesn't hit any corresponding purchase record neither on Developer Console nor game's purchase data storage.

Strategy:

Please raise the issue to Developer Relationship team for further investigation. Possible cases can be either the payment information is not successfully relayed from Google Play to Link Game's backend, or inquiry is an attempt to fake about a purchase.

Since the investigation may take time (for 1 or 2 work day due to timezone difference), it's recommended for game to think about a strategy to keep the user experience less constrained by this delay. (e.g. Gift the supposed items without verification first and later if it turns out to be an attempt to cheat, revoke the gift and blacklist the user from gift without verification.)