Tutorial: How to Implement In-app Billing in Android – Part 1

In an earlier article, I wrote about in-app billing inside an Android game app I am working on. This is the first of two follow-up articles in which I explain how to add in-app purchases to your game or other app. In this article I will walk you through the steps for the TrivialDrive example program from the Android Developers website. That website provides a sample in-app billing (IAB) app. It shows you how to do simple in-app purchases and subscriptions. To give you an idea of what that app looks like, here are a few screenshots. The sample app has you driving a car. As you drive, you consume gas. The two buttons on the right allow you to purchase gas.

After the “buy gas” button is pushed, a new dialog window is displayed. You are asked to confirm the purchase. If you confirm, you are prompted for your password.

Instructions

The sample app is fairly easy to get going. The instructions are very good. Start with the instructions on the Android Developers website.

Their first step, “Download the Sample Application”, is actually two steps. Before loading the sample application code, they ask you to make sure you have the in-app billing library installed. That library is labelled “Google Play Billing Library”, as shown below.

After that they ask you to locate the sample app, which is inside the sdk folder of the place where you installed Android. While you are loading it, you might want to give the project a new name. In the figure below, you see that I changed the name to “TrivialDriveIAB”. It’s also good to check the box labeled “Copy projects into workspace”. Doing that, leaves the original source code unchanged in its original folder, which is good should you want to start over or do another in-app billing project based on the same sample code.

After importing the sample project, check that it compiles without errors. If it does not compile, check the project preferences and be sure you are using a new version of Android (e.g. 4.4.2). Rename the project package. You need to do this because every app should have a unique package name. Then go into the AndroidManifest.xml file and change the package there too. You will also have to fix the line in MainActivity that imports the R class. Change that line so it gets R from your new package.

At this point, you should switch over to the instructions in the README file that is provided with the sample application.

The README instructions are very well written. You will end up doing all the steps, but the sequence of steps has changed since they wrote the instructions. I found that you need to have your packaged app ready in preliminary form a bit earlier than what they say.  The notes below take this into account.

Follow the README instructions. The first part starts at the Developer Console.

(From README)

ON THE GOOGLE PLAY DEVELOPER CONSOLE

1. Create an application on the Developer Console. You must use version 2, available at https://play.google.com/apps/publish/v2/ or later. In-app billing version 3 is not available in the older versions of Developer Console.

2. In that app, create MANAGED in-app items with these IDs: premium, gas Set their prices to 1 dollar (or any other price you like, but make it a small price since this is just for testing purposes).

3. In that app, create a SUBSCRIPTION items with this ID: infinite_gas Set the price to 1 dollar and the billing recurrence to monthly. Just so you are not immediately charged when you test it, set the trial period to seven days.

4. Make sure your test account (the one you will use to test purchases) is correctly listed in the “testing” section. Your test account CANNOT BE THE SAME AS THE PUBLISHER ACCOUNT. If it is, purchases won’t go through.

A few screenshots and comments follow, related to these steps. For step 1, when you add the application, you can start with the “Prepare Store Listing” button.

Enter descriptions for the app, set the price to “free”, and add placeholder images for the screenshots and marketing images.

You will find that you won’t be able to get to Step 2 until there is an APK file in place. They stop you part way through when you start to define your in-app products. You will see a screen like this one:

So it’s best to have an APK file ready. In Eclipse, you use the “Export Android Application” command on the “Export” menu. Exporting an app requires a key file so your app can be signed. Signing your app is easy if you have done it before with another app. If you are a new developer and have not built an APK file before, you have a few things to learn. Good references related to that are: (1) Preparing for Release; (2) Signing Your App; (3) article about the Keytool command. Basically what you are doing is adding a unique digital key to your packaged app. That key is used to look up the information you have defined for in-app products.

When you upload, use the Alpha Testing tab and upload the APK file. The Alpha test version will not be visible in the Google Play store.

With a preliminary APK file in place, you are ready for defining the in-app products. The screenshots below should give you an idea of what you will do during Steps 2-3.

For Step 4, the place to look for the account for testing is under “Account Details”. That is under “Settings” for your developer account. It applies to all apps that you have and not just the TrivialDrive app. Down a bit on the Account Details page is a section named “License Testing”. It is highlighted in the figure below.

Continuing on to Step 5, the instructions tell you to get the applications public key, which is used to associate your running application with the information you have entered for you in-app products.

5. Grab the application’s public key (a base-64 string) — you will need that next. Note that this is the *application’s* public key, not the developer public key. You can find the application’s public key in the “Services & API” page for your application.

The image below shows where to look for the public key. It is the very long string that is blurred out and highlighted with the orange text.

After the five steps in the Developer Console, the README instructions switch over to the code in the your TrivialDrive – IAB application in Eclipse.

IN THE CODE

1. Open MainActivity.java and replace the placeholder key with your app’s public key.

2. Change the sample’s package name to your package name. To do that, you only need to update the package name in AndroidManifest.xml and correct the references (especially the references to the R object).

3. Make sure that AndroidManifest.xml lists the updated package name!

4. Export an APK, signing it with your PRODUCTION (not debug) developer certificate

A few notes about what is going on inside MainActivity are later in the article. For now,  keep it simple and just make the editing change (Step 1)  to put the product key into the code. You can also ignore their security recommendation “TODO”. Get the sample app to work and then worry about what a real, finished app should handle. You might not need to worry about Step 2 if you renamed the package earlier, as I suggested above. While you are editing in the manifest file, fix up the “targetSdkVersion” line, making it match whatever version of Android you are using to compile with.

 <uses-sdkandroid:minSdkVersion="10" 
  android:targetSdkVersion="19"/>    

For Step 4, build your app and export it, as described earlier. Then continue with the README instructions.

BACK TO GOOGLE PLAY DEVELOPER CONSOLE

1. Upload your APK to Google Play 2. Wait 2-3 hours for Google Play to process the APK (if you don’t, you might see errors where Google Play says that “this version of the application is not enabled for in-app billing” or something similar)

As stated earlier, use the Alpha Testing tab and upload the APK file. The Alpha test version will not be visible in the Google Play store. In the top right part of the screen, you should see a “Ready to Publish” button. Publish the app.

The instructions in the README make publishing seem like it is pretty easy. In a way, it is, but there are a few things you have to take care before you can publish. They have minimum requirements that include descriptions of the product, setting prices, marketing images, etc. Fortunately, there is a good checklist that they provide. Just work your way through the items one a time. Use placeholder images for the marketing images. Here is what the checklist looks like.

Testing

The last part of the instructions in the README are related to testing.

TEST THE CODE

1. Install the APK, signed with your PRODUCTION certificate, to a test device [*] 2. Run the app 3. Make purchases (make sure you’re purchasing with an account that’s NOT your developer account with which you uploaded the app to Google Play).

Remember to refund any real purchases you make, if you don’t want the charges to actually go through.

[*]: it will be easier to use a test device that doesn’t have your developer account logged in; this is because, if you attempt to purchase an in-app item using the same account that you used to publish the app, the purchase will not go through.

One suggestion for a test device (Step 1) , for those of you that have a Nexus 7, is to set up your tablet with multiple users. I did that and made one of the users be my test user. Some of the errors you are likely to see include:

• It takes some time (2-3 hours, they say) for your app changes to be visible after publishing. If you test too early, you will see messages about there being no in-app products. The most common message is “the item you are attempting to purchase cannot be found”.
• If you run without access to the Internet, the error messages you see might not be that clear or might make you think that there is a serious problem with the app. So do check for connectivity as one of your first corrective actions.

The README reminds you to refund purchases for the test purchases. What they are referring to there is Google Wallet. As a developer, you do need to set up a Google Wallet account. The screenshots below show where you go to cancel test orders.

Next Article: Inside the Code

The focus on this article has been on getting a working example going. That is a really important step. The TrivialDrive app will be your reference app as you move ahead  with your own app. I do not recommend skipping the TrivialDrive example. There are too many things that can go wrong if you are learning the basics of in-app billing at the same time as you are adding items to your own app. Getting your own app working will be the subject of “Part 2” of this article.Topics to be covered include:

• Understanding the code and methods that you use to make in-app purchases. That includes querying to see what items are available, querying to see what items have already been purchased, starting and completing transactions to purchase an item, etc.
• Adding in-app billing code in a way that does not complicate your existing app code.
• Making it easy to track changes to the in-app billing code.
• Making design decisions about what in-app products to offer and how to present them to users.
• Information about the best practices the README authors mention related to security.

(UPDATE May 28, 2015.  Part 2 has been published.)

References

Preparing Your In-App Billing Application – the primary reference that this blog note is covering.

Preparing for Release – an article on developer.android.com that tells you what you should do to prepare for releasing an app.

Signing Your Application – another developer.android.com article; this one is about how you sign your application before releasing it.

Java keytool command, keystore files, and certificates – this note contains a lot of useful information about using the Java keytool.

In-App Billing in an Android Space War Game – my earlier article on in-app purchases for the game I am working on.