QInAppStore Class

Detailed Description

QInAppStore is used for managing in-app purchases in your application in a cross-platform way.

Using the QInAppStore

In general there are two steps to completing an in-app purchase using the API:

Initialize the store

Upon start-up of your application, connect all signals in QInAppStore to related slots in your own QObject. Then use the registerProduct() function to register the ID of each product you expect to find registered in the external store, as well as its type.

Registering a product is asynchronous, and will at some point yield one of the following two signals: 1. productRegistered() if the product was found in the external store with a matching type. 2. productUnknown() if the product was not found in the external store with the type you specified.

In addition, a transactionReady() signal may be emitted for any existing transaction which has not yet been finalized. At this point, you should check if the transaction has previously been registered. If it hasn't, register it right away. Finally, call QInAppTransaction::finalize() on the transaction.

Complete a purchase

Once the items have been successfully registered in the store, you can purchase them. Get the previously registered QInAppProduct using registeredProduct() and call QInAppProduct::purchase(). This call is also asynchronous.

At some point later on, the transactionReady() signal will be emitted for the purchase. Check QInAppTransaction::status() to see if the purchase was completed successfully. If it was, then you must save the information about the purchase in a safe way, so that the application can restore it later.

When you are done, call QInAppTransaction::finalize(), regardless of its status. Transactions which are not finalized will be emitted again the next time your application calls registerProduct() for the same product.

Types of purchases

There are two types of purchases supported by QInAppStore: QInAppProduct::Consumable and QInAppProduct::Unlockable. The former will be consumed when the transaction is completed and QInAppTransaction::finalize() is called, meaning that it can be purchased again, any number of times. Unlockable items can only be purchased once.

Consumable products are temporary and can be purchased multiple times. Examples could be a day-ticket on the bus or a magic sword in a computer game. Note that when purchasing the same product multiple times, you should call QInAppTransaction::finalize() on each transaction before you can purchase the same product again.

Unlockable products are products that a user will buy once, and the purchase of these items will be persistent. It can typically be used for things like unlocking content or functionality in the application.

Restoring purchases

If your application has unlockable products, and does not store the purchase states of these products in a way which makes it possible to restore them when the user reinstalls the application, you should provide a way for the user to restore the purchases manually.

Call the restorePurchases() function to begin this process. Granted that the remote store supports it, you will then at some point get transactionReady() for each unlockable item which has previously been purchased by the current user.

Save the purchase state of each product and call QInAppTransaction::finalize() as you would for a regular purchase.

Since restorePurchases() may, on some platforms, cause the user to be prompted for their password, it should usually be called as a reaction to user input. For instance applications can have a button in the UI which will trigger restorePurchases() and which users can hit manually if they have reinstalled the application (or installed it on a new device) and need to unlock the features that they have previously paid for.