In App Purchase / Billing


Unity In App Purchase provides a single consolidated interface towards IAP across multiple platforms. Game Framework extends this further to remove the complexity of implementing IAP by providing automatic handling and notification of purchase requests, including automatic support for common IAP types such as game and level unlocking. You can also easily simulate in app purchases to help quickly setup and test your game.

Setup

To use IAP with your Unity game you first need to setup Unity InApp Purchasing. During development there is no requirement to have a backend store (e.g. App Store or Google Play) configured as you can test all IAP using the cheat functions window (see below). You will of course need a backend store in place for final testing and release.

With Unity IAP setup you need to add the PaymentManager component to your scene (recommended onto a _GameScope gameobject).

Note: There are some bugs in the current Unity IAP implementation so if you get a message stating “Can’t add script component “PaymentManager” because the script file cannot be found…” then right click the file \FlipWebApps\GameFramework\Scripts\Billing\Components\Pyamentmanager.cs and select Reimport.

PaymentManager handles all communication with the UnityIAP backend, removing much of the complexity that you would otherwise have to deal with. To configure PaymentManager you just need to provide a list of the product id’s that you want to use. Product id’s are identifiers (the same as in your backend store) that identify the items that users can buy and can either be one of the built in IAP types that Game Framework provides (see below), or your own custom identifiers. Note that product identifiers are purely a unique ‘identifier’ and never shown to your end users; All stores allow for a descriptive name and description that are used instead.

Payment Manager

With the identifiers in place you are then ready to use IAP. PaymentManager will automatically setup the payment connections when you run your game.

Usage

As PaymentManager is a Singleton, you can reference it through PaymentManager.Instance to call any of its methods. The main methods you might use are BuyProductId() which you use to purchase a registered product and RestorePurchases() to restores all previous purchases a user might have previously made (e.g. if they reinstall the game). Note: the ability to restore purchases is a requirement to be accepted by Apple and considered best practice anyway. When billing is enabled, the standard settings window includes a button that calls RestorePurchases so it that is sufficient for your needs then you may not need to worry about this further.

You can also test IAP directly from the Cheat Functions Window (Menu | Window | Game Framework) by entering a product id that you want to simulate purchase of and then clicking “Simulate Purchase”. Note that you will need some sort of ‘listener’ for whatever product id you simulate for this to take any effect. See the topic on messaging below for more information.

Billing Cheat Window

There are also many components to help out with the built in IAP types, some of which are described below.

Messaging

We have covered how to invoke purchases, but we also need to be able to react to confirmation that the purchases have been approved.

For the built in IAP types this is handled automatically (see below). You can also extend the default behavior by listening and reacting to specific messages.

For your own custom in app purchases you will need to implement a message listener for the message ItemPurchasedMessage. ItemPurchasedMessage is sent whenever an item is purchased and contains the ProductId so that you can take the necessary action. The below sample shows how such a component might look. Add this component somewhere where you are sure will be active when the payment returns (e.g. the _GameScope gameobject if following the standard convention used in the tutorials)

Restoring purchases results in messages being sent out for each previously purchased item. These messages are the same as when the item is originally bought.

Built in IAP Types

Some of the most common IAP types that you might expect to encounter are built in and handled automatically by Game Framework. Purchase of any will result in an ItemPurchasedMessage being sent with the corresponding product id, however many also send a custom message to allow for easier handling.

Game Unlock

Some games allow users to ‘unlock the game’. That might mean removing ads or enabling new features. Game Framework enables such functionality through the GameManager IsUnlocked property (which when modified will send out a message of type GameUnlockedMessage). You can either set this property yourself based upon some specific condition, or have it set through IAP through the use of the product id “unlockgame“. If an “unlockgame” purchase is received then an UnlockGamePurchasedMessage message will be sent out and the GameManager IsUnlocked property will be set.

Within the GameStructure section there is a component EnableBasedUponGameUnlocked that can be used to conditionally enable or display gameobjects based upon the game unlocked status. THis component also automatically responds to GameUnlockedMessage’s to allow for dynamic changes.

World, Level and Character Unlock

Worlds, Levels and Characters all inherit from GameItem which, in addition to other alternatives for unlocking, also means that they support IAP. All GameItem classes have a flag IsBought that is one of several options that can be used to determine whether the GameItem should be unlocked. IsBought can be set automatically through IAP by using a product id in the format “unlock.<type>.<number>” where <type> is the gameitem type (world, level, character) and <number> is the gameitem instance number. E:g. “unlock.world.1”, “unlock.level.5”, etc… If a purchase confirmation message is received then a custom message is sent out and the gameitem is unlocked. For worlds the custom message is the WorldPurchasedMessage message, for levels LevelPurchasedMessage and for characters CharacterPurchasedMessage.

Within the GameStructure section there are various components that interact and dynamically respond to IAP including buttons for unlocking and automatically triggering IAP.

Extending

You can easily extend functionality as already demonstrated above by entering new product id’s into PaymentManager and listening to and reacting to ItemPurchasedMessages that contain the corresponding product id.

The basic functionality should cover the vast majority of scenarios, however in advanced scenarios it is also possible to create and use a subclass of PaymentManager. The function ProcessPurchase(string productId) is marked as virtual for this purpose and by overriding this you can manipulate product id strings or send custom messages.

See also

If you have any thoughts or suggestions on improvements or additions to the In App Purchase features then please let us know!