In-App Purchases for Android

by Jon (Updated on 2015-10-26)


Contents

Introduction

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.

Supported Features

Feature Supported?
Regular Purchases Yes
Consumables Yes
Restoring Purchases Yes
Susbcriptions No

Requirements

Setting up on Google Play

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.

Step 1: Set up your Keystore (if necessary)

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.

Step 2: Set the game up on Google Play

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.

Step 3: Set up Products on Google Play

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.

Step 4: Create and Assign Test Accounts

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.

Step 5: Publish the Game to Alpha/Beta Testing Channels

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.

Step 6: Get the Android Public Key

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).

billing-app-key

Setting up within Stencyl

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.

billing-app-key

Making a Purchase

Finally, we're ready to start testing purchases.

Check if In-App Billing has started

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.

Make a Purchase

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.

buy-product

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.

Testing for Success / Failure

Purchases are asynchronous (non-blocking), so you'll need to use an event to get notified of the purchase's success or failure.

bought-product

The following approach also works.

bought-product-alt

Easy Test Purchases (Static Responses)

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.

android.test.purchased
android.test.canceled

Purchase Events

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.

Consumables

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.

Usage

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.

consume-product

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.

FAQ: Handling Unmanaged Purchases

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.

unmanaged-purchase

To replicate unmanaged products in Billing v3 for new products, create a managed, consumable product instead.

Restoring Purchases

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.

restore-example

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.

restore-purchase-event

FAQ / Troubleshooting

I uploaded my APK, but the developer console won't let me add IAPs to my game.

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.

billing-app-key

What happened to unmanaged purchases?

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.

unmanaged-purchase

I can't test my IAP's in-game.

Consult Google's testing in-app billing guide for further details.

Further Reading