Construct 3 icon

Construct 3

Documentation

Mobile IAP

Published 27 Sep, 2017
1,016 words
~4-7 minutes

The Mobile IAP plugin allows a game to use consumable and non-consumable in app purchases (IAP) on Android and iOS.

Consumable vs Non-consumable

Non-consumable purchases can be bought once per user. A good use for this type of purchase is to distribute your game for free but with the majority of the content locked from the user. To unlock the rest of the content the user can purchase a premium upgrade. The plugin keeps track of these types of purchases for you across multiple user devices.

Consumable purchases can be bought multiple times by each user. A good use for this type of purchase is to enable a timed bonus or virtual currency. You need to keep track of these types of purchase yourself.

Setup

Before adding purchases to you game you will need to set up your application on Google Play and/or the App Store.

To register an app on Google Play visit https://play.google.com/apps/publish. To enable in app purchases you will also need to setup a Google payments merchants account at http://www.google.com/wallet/merchants.html.

To register an app on the App Store visit https://itunesconnect.apple.com/login

Registration stage

When making IAP events, the first thing you need to do is to complete the plugin's registration stage. You won't be able to make any purchases or check if a user owns a product until this is done. For each product you have you must call the Register product action with the product ID and type (consumable or non-consumable). If you are supporting Android you must call the Set Public Key action with your application's public key (you can find this on Google Play). To finish registration you must call the Complete Registration action. If registration succeeds then On Registration Success triggers. After this you are free to check if a user owns a product or purchase available products. You can use all these actions in an On start of layout event.

Keeping track of purchases

It's important to consider how your going to keep track of user purchases before you start adding IAP events. Non-consumable purchases are tracked by the app stores, so you can easily find out if the user owns it. However, consumable products are a bit more tricky. The app stores don't track these, so you need to store information about these yourself. Initially it may seem appealing to store this information in Local Storage or similar, and while this works quite well for local testing it has a big issue: synchronization. If a user shares their account across multiple devices only the device that performed the purchase will know of it. This is also a pretty big issue if they move to a new device or reinstall your game, as they will lose content they have paid for and this tends to upset users. So best practice is to store this information in a remote database somewhere, that you can connect to from your game to check the purchases a user has made.

Exactly how you set this up very much depends on the game you are making and if you are offering a short timed bonus you may not even need a database. A simple setup would be a single number representing a user's balance of "magic gems" or similar. With a more complicated game you may choose to store the entire game state on the server; the world, balance of virtual currency, purchases of virtual goods made with virtual currency and purchases of virtual currency with real currency. A complete setup like this has the bonus of a user not losing virtual goods when moving device, and being able to play the game on multiple devices, but does increase your network dependence.

IAP properties

The Mobile IAP plugin has no properties.

IAP conditions

On Purchase Success

Triggers when a specific product purchase succeeds.

On Any Purchase Success

Triggers when any product purchase succeeds.

On Purchase Failed

Triggers when a specific product purchase fails.

On Any Purchase Failed

Triggers when a any product purchase fails.

On Registration Success

Triggers when registration has been completed (after the Complete registration action). This is a good time to check if a product is owned. You should wait for this trigger before attempting any purchases.

On Registration Failure

Triggers when registration failed. If this occurs then you won't be able to make any purchases.

On Product Available

Triggers when a specific product becomes available to purchase.

On Any Product Available

Triggers when any product becomes available to purchase.

Product Owned

True if the current user owns the product.

Product Available

True if the current user can purchase the product.

Store Registered

True if the registration stage successfully completed.

IAP Actions

Register Product

Add a new product to the plugin by specifying the ID and type (consumable or non-consumable). This can only be called in the registration stage.

Complete Registration

Ends the registration stage. After this has been called you will no longer be able to register products. This must be called before you can purchase products. On registration success will trigger if successful.

Restore Purchases

Restores user purchases. This is not necessary on Android.

Set Public Key

Sets the application's public key. This is used to identify the application to the store on Android, and isn't used on iOS. iOS uses the bundle ID instead.

Purchase Product

Triggers the purchase of a product with a specific ID. This product must be available to purchase.

IAP Expressions

ProductName(ProductID)

Get the name of a product from its ID. This is the localized name provided by the store, you should use it instead of a hard-coded string.

ProductPrice(ProductID)

Get the price of a product from its ID. This is the localized value provided by the store, you should use it instead of a hard-coded value.

ProductDescription(ProductID)

The description of a product from its ID. This is the localized string provided by the store, you should use it instead of a hard-coded string.

ProductID

The ID of the current product in a trigger.

ErrorMessage

In an error trigger, the relevant error message, if any.

All Contributors

  • Nepeo's avatar
    Iain Shorter
    Last edited 2 Nov, 2017
    ~6,824 chars in 15 edits
  • Ashley's avatar
    Ashley Gullen
    Last edited 4 Oct, 2017
    ~2,303 chars in 1 edits