Using the In-App Billing Adobe AIR native extension for Android

With the In-App Billing Extension for Android from Milkman Games, you can rapidly integrate in-app purchasing into your mobile AIR application using ActionScript 3.

The In-App Billing Extension for Android is a 100 percent native Java solution that enables you to:

• Offer your app for free and earn revenue with in-app purchases
• Make a purchase with just a few lines of code
• Jumpstart development with a complete sample application, ActionScript 3 documentation, and a getting started guide
• Invoke testing methods to verify purchases before your app goes live

Before you can use In-App Billing in your application, you need to set it up properly on the Android Market website.

1. Go the Android Market Publishing Home page and login with your developer account.
2. If you're adding In-App Billing to an existing application, select the application from the list. Click the APK Files tab, and upload a new APK file. Do not publish it yet, but click Save to save a draft.
3. If you're adding In-App Billing to a new application, click Upload Application. Upload your new application's first draft APK file. Enter the required information and click Save, but do not click Publish yet. If you're just making a test app, the In-App Billing Extension for Android package includes a /tutorial folder with some stock screenshots and icons that you can use for this process.
4. Next, you need to add some products that can be purchased via In-App Billing. On the home screen, begin by clicking the In-App Products link for the application to which you'd like to add products (see Figure 1).

1. To add a product, click Add In-App Product.

1. For Purchase Type, choose between Managed Per User Account and Unmanaged. A managed item is something that the user may purchase once and only once, and then owns forever, such as pack of new levels for a game. An unmanaged item is something that can be purchased again and again, such as a magic spell.
2. For In-App Product ID, type a unique string identifier to represent your item. Take note of this ID, as you'll need to reference it in your game code later. Complete the rest of the required information, providing an appropriate title, description, and price (see Figure 2).
3. Click Publish. This will Publish the product so it can be tested. You do not need to publish your draft application yet (and should avoid doing so during testing). When you're done, return to the Android Developers Home page from the tab bar at the top.
4. Next, retrieve your In-App Billing Public Key by clicking Edit Profile from the Home page (see Figure 3). Also, take note of the email address listed above Edit Profile. This is the Google account associated with your developer account. In this article, I will refer to this email address as your Registered Developer Email.

5. Copy your public key in the Licensing and In-App Billing section (see Figure 4) to the clipboard. Open a text editor, paste your key from the clipboard, and save it in a text file. You'll need this later to complete your app.

6. In the Test Accounts area, type a Gmail address you control, other than your Registered Developer Email. If you don't have any other Gmail accounts besides your Registered Developer Email, you should create a new one now at Gmail.com for this purpose. In this article, I'll refer to this new address as your Test Account Email.
7. Click Save.

The next step is to add the com.milkmangames.nativeextensions.AndroidIAB.ane library to your project. (If you are not using Flash Builder 4.6 and later or Flash Professional CS6 and later you'll need to add the AndroidIABAPI.swc library instead.)

In Flash Professional CS6:

1. Create a new project of the type AIR for Android.
2. Choose File > Publish Settings.
3. Click the wrench icon next to Script for ActionScript Settings.
4. Select the Library Path tab.
5. Click Browse For Native Extension (ANE) File and select the com.milkmangames.nativeextensions.AndroidIAB.ane file.

In Flash Builder 4.6:

1. Go to Project Properties (right-click your project in Package Explorer and select Properties).
2. Select ActionScript Build Path and click the Native Extensions tab.
3. Click Add ANE and navigate to the com.milkmangames.nativeextensions.AndroidIAB.ane file.

In FlashDevelop:

1. Copy the AndroidIABAPI.swc file to your project folder.
2. In the explorer panel, right-click the SWC and select Add To Library.
3. Right-click the SWC file in the explorer panel again, select Options, and then select External Library.

You can start using the In-App Billing extension with a few simple calls. See example/AndroidIAB.as for a full example that shows how to use the ActionScript API.

Follow these steps to get started:

1. Import the API Classes:

2. Initialize the API by calling AndroidIAB.create() . You can check the AndroidIAB.isSupported() method first, to ensure the current platform is Android and not an unsupported platform (like iOS or Windows):

3. Once create() has been called, an instance of the AndroidIAB API is available statically by accessing AndroidIAB.androidIAB. Add event listeners for all possible API responses:

4. Call the AndroidIAB.androidIAB.startBillingService("yourPublisherPublicKeyHere") method to begin interactions with the Android In-App Billing server. Instructions on obtaining your publisher public key were provided in Setting up your app with your Android Market publishing account. If the current device does not support In-App Billing (because it doesn't have Android Market, for instance), you'll receive the AndroidBillingEvent.SERVICE_NOT_SUPPORTED event. Otherwise, when the service is ready, you'll receive the AndroidBillingEvent.SERVICE_READY event; once that happens, you may begin calling the other API methods to make purchases.

1. To start the item purchase process, call purchaseItem(itemId) , where itemId is one of the In-App Product IDs you created with your Android Market publishing account:

2. When the process completes you will receive one of the following events:

• AndroidBillingEvent.PURCHASE_SUCCEEDED – This event will fire if the purchase went through successfully. The itemId property of the event object will be the In-App Product ID of the item the user just bought.
• AndroidBillingErrorEvent.PURCHASE_FAILED – This event will fire if an error occurred and the purchase did not go through. The itemId property of the event object will be the In-App Product ID of the item the user just attempted to buy. The errorID property will indicate the specific reason of the error (see Table 1).
• AndroidBillingEvent.PURCHASE_USER_CANCELLED – This event will fire if the user cancelled the purchase by closing the checkout dialog box or pressing the Back button. The itemId property of the event object will be the In-App Product ID of the item the user just attempted to buy.

Table 1. AndroidBillingErrorEvent.errorID values and descriptions

If you receive AndroidBillingErrorID.REASON_DEVELOPER_ERROR then there is a problem with your code or configuration. Verify your application descriptor file is set up correctly; see Updating your application descriptor file for details. This error will also be reported if you attempt to purchase an item when the Google account associated with the device is the same as your Registered Developer Email because Google won't let you buy items from yourself. You can avoid this error by switching the Google account associated with the device to a Test Account Email, as described in Setting up your app with your Android Market publishing account.

The Android Billing service works in asynchronously; in other words, events can be dispatched at any time that an item's purchase state changes, even if your application is running in the background. It is up to you as the developer to handle these events, and keep track of what items the user does or does not own.

For instance, it is possible for you to cancel or refund a purchase using the Android Market Developer website. When you do this, your application will receive an event indicating the refund or cancellation (even if it's not in the foreground). When this happens, your app should update its state appropriately, by taking away the item and setting a variable to indicate the item is no longer in the user's possession.

One way you might manage this is to keep a SharedObject instance updated locally, with information about each item that you sell. When you get an AndroidBillingEvent.PURCHASE_SUCCEEDED event, update the SharedObject instance to indicate that the item is now owned. You may also receive a AndroidBillingEvent.PURCHASE_REFUNDED or AndroidBillingEvent.PURCHASE_CANCELLED event. In these cases, you could update your SharedObject instance to indicate that the particular item has been removed.

If you have an unmanaged item, such as a consumable magic spell that can be bought and used multiple times, you are also responsible for keeping track of how many times the item has been bought and used in your application logic.

For a simple example that shows how to manage the full transaction event cycle, see the /example/IABExample.as class in the In-App Billing Extension for Android package.

Any In-App Purchases you marked as managed in the Android Market Developer website are treated as one-time, permanent purchases. This designation is intended for items such as an additional game level or a virtual hat your user gets to keep.

Because these items are managed, Google stores a record of whether the user has purchased them or not. Of course, you still must also maintain your own records of this within your application.

It is possible that the user will uninstall your application from the device, or get a new device and install your application on it. In this situation, you'll need to restore all items the user has previously purchased. To detect if the user has re-installed your app (or possibly just installed it for the first time), you could, for example, keep a variable named firstTimeuse with a default value of true in your SharedObject instance. If firstTimeUse is set, your app can call the restoreManagedTransactions() function, which will replay all the stored managed purchase events for that user. Your app can then listen for the events and update its records to reflect the user's purchases. It would then set firstTimeUse to false so the process is not repeated on the next application start. RestoreManagedTransactions() is not meant to be used every time your application runs, just when it is being run for the first time on a new device.

The following code demonstrates the restoreManagedTransactions() call:

After the call is made, one AndroidBillingEvent.PURCHASE_SUCCEEDED event will be fired for each managed item the user has already purchased (if any). The event handler can check the itemId property of the event object, and grant the user the item.

When there are no more items to be restored, an AndroidBillingEvent.TRANSACTIONS_RESTORED event will be dispatched.

If an error occurs with the call, AndroidBillingErrorEvent.TRANSACTION_RESTORE_FAILED will be dispatched instead.

Again, the /example/IABExample.as class in the in the In-App Billing Extension for Android package shows an example of how to manage the full transaction event cycle.

The In-App Billing Extension for Android provides a number of built-in test methods that you can use to ensure you've set up billing correctly. These methods will attempt to contact the billing service, and dispatch the proper events for different fake item use cases, such as a refund or successful purchase. You should make sure these methods work for you before moving on to integrating your real items.

These calls will work whether the Google account associated with your device is a Registered Developer Email or a Test Account Email, as defined earlier. The following examples should be tested separately with event handlers set up to process the results; they are not intended to be called one after the other in succession.

It is also possible to test the purchase flow in an unpublished application using real In-App Purchase IDs, with a few restrictions:

• The Google account associate with the device must be a Test Account Email, and not a Registered Developer Email. This is because Google will not allow you to buy items from yourself. Unfortunately, the only way to change the Google account for the device is to perform a factory reset, which is done by selecting Settings > Privacy > Factory Reset; enter your Test Account Email when prompted.
• The application must be Saved in the Android Market Developer website, as described in Setting up your app with your Android Market publishing account. It does not need to be Published, however. You can test without making your application public.
• The In-App Purchase IDs (each referenced as an itemId in your code) you are testing must be Published, as described in Setting up your app with your Android Market publishing account. The application itself need not be published, however.
• Real money will be withdrawn from the account associated with the Test Account Email. You can prevent this by logging into the Android Market Developer website after making a purchase, and clicking Cancel Entire Order or Refund Some Money. This will cause an asynchronous AndroidBillingEvent.PURCHASE_CANCELLED or AndroidBillingEvent.PURCHASE_REFUNDED event to fire.

You need to configure your AIR application descriptor file to use the AIR 3.0 SDK (or later), include the In-App Billing extension, and update the Android manifest additions with some Android Billing specific settings. For a working example, see example/app.xml.

1. Set your AIR SDK to 3.0 in the app descriptor file:

2. Include a link to the extension in the descriptor:

3. Update your Android manifest additions. The android.permission.INTERNET and com.android.vending.BILLING permissions must be present for In-App Billing to work. You also must add the com.android.vending.billing.IN_APP_NOTIFY , com.android.vending.billing.RESPONSE_CODE , and com.android.vending.billing.PURCHASE_STATE_CHANGED actions within the <intent-filter> element, as shown below:

If you're using Flash Builder 4.6 or later, or Flash Professional CS6 or later, and have added the In-App Billing for Android extension library as described above, then you can compile as you usually do directly from the IDE. If not and you are building your app with the extension from the command line, then you'll need to specify the directory containing the com.milkmangames.nativeextensions.AndroidIAB.ane file.

Here is an example build command line:

If your app is not receiving events as expected, try these tips:

• Make sure you've saved a draft of the application to the Android Market Developer Website as described in Setting up your app with your Android Market publishing account.
• Make sure you've updated your application descriptor file as described in Updating your application descriptor file.
• Make sure the Google email address associated with your device is a Registered Developer Email or a Test Account Email.
• If you're testing the IABSample application as is, make sure that you've created the In-App Product IDs that it uses: a managed product named my_levelpack and an unmanaged one named my_spell . See Setting up your app with your Android Market publishing account for information on how to set up products.

Now that you have the In-App Billing Extension for Android up and running, you may want to explore the ActionScript 3 documentation or check out the Game Center, iAd, AdMob or other tools from available from Milkman Games.