As of late 2021, we are in the process of updating Stencylpedia and fixing up outdated & broken content. Thanks for your patience!

59,876

Views

Beginner

Level

10

Comments

In-App Purchases for Android

by Jon (Updated on 2015-10-26)


Contents

  • Introduction
  • Requirements
  • Walkthrough
    • Setup: Google Play
    • Setup: Stencyl
    • Making a Purchase
    • Purchase Events
    • Consumables
    • Restoring Purchases
  • Troubleshooting
  • Further Reading

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

  • A Google Play developer account.
  • A Google Payments merchant account. You can create one at the same time that you create a dev account.
  • A non-rooted Android device running 4.0 or later.
  • The most current version of Google Play must be installed.

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:

  • Add and publish the products you wish to test to the developer console.
  • Create test accounts by adding Gmail accounts to Settings > Account details in the developer console.
  • Within 15 minutes, those users can begin making test purchases in your app.

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

  • Inside the Developer Console, open up the entry for your game.

  • Select Services & APIs.

  • Scroll down to Your License Key for this Application. Make note of this for the next section.

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.

  • Ensure that the Enable Purchases checkbox is checked. It's inside Settings > Mobile > Monetization.

  • Enter in your Android Public Key on that same page (Settings > Mobile > Monetization). This is the "License Key for this Application" that you obtained in the previous section.

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.

  • Player can purchase goods
  • A purchase succeeds
  • A purchase fails
  • A purchase is canceled
  • A product info request succeeds (required to get title/price/description, you can't use these blocks without this event)

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

Print Article Edit Article How to Edit an Article
Disclaimer: Use comments to provide feedback and point out issues with the article (typo, wrong info, etc.). If you're seeking help for your game, please ask a question on the forums. Thanks!

10 Comments

yuliay
What do you think about Android Pay? Cleveroad (https://www.cleveroad.com/blog/lat est-trends-in-android-application-d evelopment-in-2017) wrote that the benefits of Android Pay lie in the possibility to effect payment by simply unlocking your device. By the way, the device must be NFC-compatible and run on KitKat 4.4 or later versions. To make the payment you should unlock your device and place it near the contactless terminal. That's all!
Besides, if you buy something cheaper than 30 pounds, you don't even need to unlock your device, just its screen should be on. Sounds really great

-1 7 years, 9 months ago
Jon
I've rewritten this article from scratch. It should now accurately reflect the current state of billing and what Stencyl supports.
-1 9 years, 2 weeks ago
CanadianHobo
The unmanaged is a modified managed:
http://community.stencyl.com/index. php/topic,37093.30.html

0 9 years, 1 month ago
CanadianHobo
There is no longer unmanaged products; how can you make consumables now?
0 9 years, 1 month ago
1MrPaul1
testing purchases in non published apps is not avaible any more....
We need to start beta test first

0 9 years, 2 months ago
Bhoopalan
The content is incorrect. The <if <player can make purchase>> block works only with iOS I think. It doesn't work with Android. I was struggling without knowing what went wrong with the inapp purchase.

I removed the <if <player can make purchase>> block and directly added the buy button. It now works fine for me. I also completed a test purchase. :) I started a topic when there was an issue. http://community.stencyl.com/index. php/topic,41719.msg234301.html#msg2 34301

0 9 years, 5 months ago
dawntcherian
For adding in-app product data through Google play developer API view https://docs.google.com/document/d/ 1vCIbhhoZkhfV3DHCBYRTKYoGskLUvPah9I AYIPgZ9NA/edit?usp=sharing
0 9 years, 9 months ago
dharmpal31
Very Easy and Latest step by step in-app-billing-v3 tutorial please try this:
http://androidfrenzy.weebly.com/blo g/easy-way-to-implement-in-app-bill ing-v3

0 9 years, 9 months ago
Slimefon
Jon, once the Android's v3 billing is perfect and all, can you update this tutorial here as well? We need tutorials for the new android v3 purchases. Thanks.
1 9 years, 10 months ago
Jezus101
Correct Terminology is "Rooted" phone, we dont jailbreak and anyone that does this to their android phone knows this
2 10 years, 8 months ago

Sign In to Comment