IAP object

IAP stands for In-App Purchases. The IAP plugin allows access to purchasing functionality on a variety of stores.

Projects using the IAP plugin cannot be exported with the Free edition. A license is necessary to be able to export projects using IAP. Note that the Free edition may not be used for commercial purposes.

Supported stores

Currently the IAP plugin supports these platforms:

  • PhoneGap Build (iOS + Android)
  • CocoonJS (iOS + Android)
  • Ejecta (iOS)
  • Windows Store (Windows 8+, Windows Phone 8.1+)
  • Blackberry 10
  • Amazon Appstore
  • Tizen

Platform documentation

Each operating system has a different way of configuring in-app purchases. Please refer to vendor documentation for further help. Links are provided below.

iOS: configuring with iTunes Connect
Android: Google Play In-App Billing
Windows Store: MSDN documentation
Blackberry 10: Blackberry payment service
Amazon Appstore: Amazon documentation

Please note vendor documentation may refer to code samples. You can ignore these since Construct 2's IAP plugin handles this for you. The main parts of the documentation you need to refer to are how to register seller accounts, how to add the items available for sale to the app, and testing and publishing. If a store has a test or developer mode at all, then the Test mode property of the IAP object will enable or disable that mode for the store.

Basic usage

To access in-app purchasing features, the basic usage is as follows:

  1. On start of layout, use the Add product ID action to add the product IDs you will be using, e.g. "product1,product2,product3".
  2. After that (still in the 'Start of layout' event), use the Request store listing action. This starts downloading the names and prices of the given products. Some platforms require this information to be available for the IAP features to work.
  3. When On store listing success triggers, the product names and prices are available, and purchases can start being made or checked with the Has product condition.

Terminology

The plugin uses a Product ID to refer to an individual item available for sale. This is a short unique string, e.g. "myitem". Some stores instead refer to this in different ways, such as the "SKU". This does not matter; you can still enter it as a product ID, so long as it is the string that identifies the item. This is usually also different to the product name.

App purchases

The Windows Store allows the app itself to be purchased, e.g. to unlock premium features. The IAP has features such as the Purchase app action to support this. However the other platforms do not support the app itself being purchased. To make sure your events are compatible with other stores, purchasing the app will translate in to purchasing a product with the ID "app".

Using Test Mode

The Test mode property of the IAP object should be set to Yes during development, but must be set to No before publishing. In Test Mode, store purchases are simulated. Different stores have different terminology for this, including "Test mode", "Sandbox mode", or "Developer mode". Each store also handles test mode in its own way; in many cases all purchases will be forgotten each time you restart the app, allowing you to test that the purchase flows work.

Publishing

When publishing your app, it will be necessary to set up the store with the list of items you wish to have available for sale. The process for this is different for each platform and is usually part of the publishing process. Be sure to carefully record any product IDs you use in your events, and make sure you add an item with each product ID when publishing. Note that as described in the App purchases section above, if you use app purchases you should add a product with the ID "app" to represent purchasing the app itself on all stores except the Windows Store.

IAP properties

Test mode
See the section on Using Test Mode above.

Item group ID (under Tizen store settings)
This setting applies only to apps published to the Tizen store. When publishing your app, create an item group for the IAP items you want available in the app, and then enter the item group ID in to this property.

IAP conditions

Has product
Test if a given product ID has been successfully purchased by the user. Note that in some cases this will be false for the first few seconds of the app running even if the user has purchased the item, and then later become true when the store finishes loading the store status in the background. Try to avoid using this condition before On store listing success triggers.

Is app purchased
On the Windows Store, test if the app itself has been purchased. On other platforms, tests if the product ID "app" has been purchased.

Is store available
True if a supported store is currently available and purchases can be made. False on unsupported platforms or if no store is available (such as in an ordinary web browser).

On any purchase success
On any purchase failed
Triggered after any purchase finishes to indicate whether it was successful (and the item is now owned) or unsuccessful.

On purchase success
On purchase failed
Triggered after the purchase of a specific product ID finishes, to indicate whether it was successful (and the item is now owned) or unsuccessful.

On store listing success
On store listing failed
Triggered after the Request store listing action has completed, to indicate whether the store listing was successfully retrieved. After On store listing success you can then check whether products are purchased, make new purchases, and retrieve lists of available items and their details.

IAP actions

Add product ID
Use on start of layout to indicate all the product IDs the app will be using. The action can be used multiple times, or with a comma-separated list of product IDs to add multiple products at once. See the section on Basic usage above for more information.

Purchase app
On the Windows Store, request to purchase the app itself. On other platforms, request the purchase of the product ID "app".

Purchase product
Request to purchase a particular product by its product ID.

Request store listing
Request the details of available and purchased items from the store. This must be used on start of layout. See the section on Basic usage above for more information.

Restore purchases
Update the status of which items have been purchased from the store.

IAP expressions

AppName
AppPrice
Return the name and price of the app itself on the Windows Store. On other platforms, returns the name and price of the product ID "app".

Error message
In a "failed" trigger, the error message text if available.

ProductID
The ID of the relevant product in a trigger, e.g. On any purchase success.

ProductName(productid)
ProductPrice(productid)
Return the name or price of a product available for purchase by its product ID. This information is only available after On store listing success triggers.

Tags: