by Jon (Updated on 2015-10-26)
In-App Purchases (IAP) let you sell goods and services from within a game. This gives developers more opportunities to monetize the free app by providing downloadable, supplementary content (new levels or game modes), an unlock for the full game and much more.
Tip: Just want to skip to testing? It is possible to test purchases without setting anything up using static product ID's. This is good for testing basic connectivity to Google Play.
Before doing anything, you must set up your keystore within Stencyl. Consult our Publishing to Google Play guide for details on this process.
Note: If you already have a Keystore (made outside of Stencyl), you must still tell Stencyl about it. Read the guide for details.
First, you must set up your game on the Google Play Developer Console, the Google equivalent to iTunes Connect. If you haven't registered for the Google Play Developer Console before, you will be prompted to do so.
Now that you've created an entry for your game, you can begin adding products (purchases) to your game.
Consult Google's guide on Administering In-App Billing for a walkthrough of this process.
Test accounts let real testers with real accounts make test purchases of your app without being charged. In order to do this, you can designate (via e-mail address), people with Gmail accounts who have this privilege.
In summary, the process goes as follows:
Consult Google's guide on Testing In-App Purchases for a complete walkthrough.
In order to test purchases, the game must published.
Google provides various channels (Alpha/Beta) for publishing the game, so that it does not show up in public listings and can only be installed by testers you designate. Consult Google's guide for details.
In order to test out purchases, you'll need to get your app's public key (now referred to as License Key on Google's end).
Inside the Developer Console, open up the entry for your game.
Select Services & APIs.
Now that you've set everything up on Google Play, you'll need to do a few more things in Stencyl before you can begin.
Ensure that the Enable Purchases checkbox is checked. It's inside Settings > Mobile > Monetization.
Finally, we're ready to start testing purchases.
Before doing anything with in-app billing, we need to check if the service has started. Use the following Purchase event (under Add Event > Mobile > Purchases) to accomplish this. Store the value inside a boolean Game Attribute, so you can refer to it in the future.
Warning: You can't do the following on Android at this time due to a bug. This was fixed on Oct 25, 2015, but we're keeping this up for now.
With the switch over to Billing v3, it's no longer necessary to request purchases on Android. Just buy the product directly by passing in its product ID using the buy block, located under Game > Mobile.
The ID you use is the Product ID you entered into the Google Play dashboard.
Recall from above that we want to check if in-app billing has started, so we used an event and stored that in a game attribute. What's where canMakePurchases comes from.
Purchases are asynchronous (non-blocking), so you'll need to use an event to get notified of the purchase's success or failure.
The following approach also works.
If you'd like to test out purchases without setting up an entry on Google Play, you can use the following product IDs that Google has designated for testing.
Just like on iOS, purchase events are available, so your app is informed when purchases succeed, fail and so forth. The following events apply to Android.
Consumable purchases are products that can be used. More specifically, these are products that can be repurchased over and over again. This contrasts with regular (non-consumable) purchases that stay with the user forever.
A common example of a consumable purchase is virtual currency. Some games (particularly those that make you wait to progress), will sell a special currency that can be used in game to speed the game up or let you purchase special items that accomplish the same.
Consumables are "used" using the use product block (same block as buy product, click the dropdown). Make sure to check that the user has at least 1 of that product before using, as shown below.
If consumption was successful, you will receive a purchase-succeeded event. If it failed, you will receive a purchased-failed event. Be sure to handle these events - do not let the user consume the products immediately.
In Billing v3, unmanged products are treated as managed products. You don't have to create a new entry for them, but you do have to take one extra step to let a user "repurchase" them.
To replicate unmanaged products in Billing v3 for new products, create a managed, consumable product instead.
If a user installs your app in a different device, or if the user has wiped their device, they'll want to get their purchases back for your app. Restoring Purchases is the feature that enables this. The way it works is that when a restore happens, the game acts as if the player made all those purchases again.
Restoration happens automatically when a game launches, but you can force a restore to happen (such as providing a block to let the user request this).
Use the restore purchases block under Game > Mobile to forcefully initiate this process.
When this happens, you will receive a series of purchase-restored events, each corresponding to a product). It's your task to react to these events in an appropriate manner.
Before you export and upload your game, ensure that the Enable Purchases checkbox is checked for your game, otherwise the Google developer console will not let you add IAPs. Enable Purchases is located inside Settings > Mobile > Monetization.
Google has made everything a managed purchase. The closest thing to an unmanaged purchase is a consumable, managed purchase. To gracefully handle existing "unmanaged" purchases, do the following to let a user "repurchase" them.
Consult Google's testing in-app billing guide for further details.