Using the Amazon In-App Purchase Adobe AIR native extension for Android and Kindle Fire

The Amazon Appstore, and the immensely popular Kindle Fire, represent a huge market for developers and a great opportunity to monetize apps. With the Amazon In-App Purchase Extension for Adobe AIR from Milkman Games, you can integrate Amazon's In-App Purchase system in your AIR and Flash apps, using a familiar and straightforward ActionScript 3 interface.

The Amazon In-App Purchase Extension for Android and Kindle fire is a 100 percent native Java solution that enables you to:

• Offer your app free and earn revenue with in-app purchases
• Earn revenue from Amazon's Free App Of The Day promotion via optional purchases
• Integrate quickly and enable purchases with just a few lines of code
• Support consumable, entitlement, and subscription items

Before you can use Amazon in-app purchases, you must define the purchasable items on the Amazon developer website.

1. Go to http://developer.amazon.com and login with your developer account credentials.
2. If you're creating a new application, click Add New App from the Home screen (see Figure 1). If you're adding in-app purchases to an existing app, skip to step 4.

3. Fill in the title, form-factor, description, and contact info for your app, and then click Save (see Figure 2).

4. Back on the Home screen, click Actions next to the application you'd like to add in-app purchases to and select In-App Items (see Figure 3).

On the In-App Items screen, select Add In-App Item on the top right of the screen. You'll be presented with three options: Add Consumable, Add Entitlement, or Add Subscription (see Figure 4).

A Consumable Item is a product that may be purchased multiple times and is then used up or consumed in your app. An example of a consumable item would be a pack of game coins. The users might buy the coins, spend them inside the game world, and then buy more again.

An Entitlement Item is a product that may be purchased only once, and then is owned forever. An example of Entitlement item would be a pack of new levels in a game, or a full-version feature unlock in a utility app.

A Subscription item is purchased to enable a feature or set of content during a given time frame. When the time expires, the subscription may be renewed. A magazine that delivers a new issue digitally every month is an example of a Subscription item.

Select the type of Item you want to add. The example below uses a Consumable item.

5. On the next screen, enter the details for the consumable item. The Title and Description fields will be displayed to the end user, along with any multimedia content you upload. The SKU field is a unique identifier for this item. The user will never see it, but be sure to keep track of the SKU you choose as you'll need it later to purchase the item programmatically from within your app. When you're done setting up the item, click Save (see Figure 5).

If you want to add additional in-app purchases to your app, repeat the process above as needed.

To test your in-app purchases before submitting your app to the Appstore, you'll need to create a special file in the JSON format that contains all the metadata for your purchases. While in sandbox mode, this file will determine how the app responds to purchase requests.

The following example shows the format this file should take. It includes a consumable item with the SKU my_spell for an entitlement item named my_levelpack as an example. Be sure that the SKUs, titles, descriptions, and other data match what you entered in the developer portal.

The file should be named amazon.sdktester.json. In the /example folder of the extension package, you can find a reference example of this file.

For more detailed information on the file format, see https://developer.amazon.com/sdk/in-app-purchasing/documentation/testing-iap.html#Create JSON .

1. Create a file called amazon.sdktester.json in your favorite text editor, using the following example as a guide. Use the SKUs and other information for your own purchases:

2. Save the file to a location on your computer.
3. Plug your Kindle Fire or other Android device into the USB port on your computer.
4. Open a Command Prompt on Windows (Start > Run, type cmd, and press Enter) or the Terminal on iOS (Applications > Terminal).
5. Navigate to the location of the JSON file. On Windows, if the file was saved in C:\dev\ then type cd c:\dev and press Enter.

   On iOS, if the file was saved in /yourusername/dev, then type cd /Users/yourusername/dev and press Return.

6. Run the adb program that's included with the Android SDK. (If you don't have the SDK, you can get it at http://developer.android.com/sdk/index.html). You'll be executing the push command, passing the location of the JSON file as the first parameter and /mnt/sdcard as the second parameter.

   On Windows, if the Android SDK is located at C:\dev\android-sdk, type c:\dev\android-sdk\platform-tools\adb push amazon.sdktester.json /mnt/sdcard and press Enter.

7. On iOS, if the Android SDK is located /Users/yourusername/android-sdk, type ./Users/yourusername/android-sdk/platform-tools/adb push amazon.sdktester.json /mnt/sdcard and press Return.

Before you can test Amazon Purchases locally, you also must install a special test application called the Amazon SDK Tester. The App is included in the Amazon SDK, which can be downloaded from https://developer.amazon.com/sdk.html .

To install the app, you'll again use the adb command from the Android SDK:

1. Plug your Kindle Fire or other Android device into the USB port on your computer.
2. Open a Command Prompt.
3. Navigate to the location of the Amazon SDK tools and run the adb program that's included with the Android SDK. You'll be running the install command and passing the Amazon SDK tester app APK as a parameter.
4. On Windows, if the Amazon SDK is saved in C:\dev\In-App-Purchasing and the Android SDK is located at C:\dev\android-sdk, then execute the following commands:

5. On iOS, if the Amazon SDK is saved in /yourusername/dev/In-App-Purchasing and the Android SDK is located /Users/yourusername/android-sdk, then execute the following commands:

The next step is to add the com.milkmangames.nativeextensions.AmazonPurchase.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 AmazonPurchaseAPI.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.AmazonPurchase.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.AmazonPurchase.ane file.
4. Select ActionScript Build Packaging > Packaging > Android.
5. Select the Native Extensions tab, and click the Package checkbox next to the extension.

In FlashDevelop:

1. Copy the AmazonPurchaseAPI.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.

The Amazon In-App Purchase extension can be up and running in a few simple calls. See example/AmazonExample.as for a full example.

Follow these steps to get started:

1. Import the API Classes:

2. Initialize the API by calling AmazonPurchase.create() . You can check the AmazonPurchase.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 AmazonPurchase API is available statically by accessing AmazonPurchase.amazonPurchase. Add event listeners for all possible API responses:

At any time after you've initialized the API and set up the event handlers, you may receive an AmazonPurchaseEvent.PURCHASES_UPDATED event. This event includes a parameter, receipts , which contains an array of AmazonPurchaseReceipt objects for any non-consumables the user has purchased. The following code example shows how to iterate through those receipts:

You may use the AmazonPurchase.amazonPurchase.loadItemData() method to retrieve details such as titles, descriptions, and icons as they relate to a given set of SKUs; for example:

On completion, this function will dispatch an AmazonPurchaseEvent.ITEM_DATA_LOADED event that contains the details for the provided SKUs. If the request fails, AmazonPurchaseEvent.ITEM_DATA_FAILED will be dispatched.

The following code demonstrates iterating through itemDatas and displaying SKUs. It also checks the property unavailableSkus , which is an array of any SKUs you submitted that are not valid:

Follow these steps to initiate and item purchase from your app's code:

1. To start an item purchase and present the user with the checkout dialog box, use the purchaseItem(itemSku) method, where itemSku is one of the product SKUs you created earlier; for example:

2. When the purchase process complete, you will receive one of the events shown in Table 1.

Table 1. Purchase events.

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

1. Set your AIR SDK to 3.0 (or higher) 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 permission must be present for Amazon In-App Purchase to work. You also must add the com.amazon.inapp.purchasing.NOTIFY 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 Amazon In-App Purchase 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.AmazonPurchase.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 added the appropriate manifestAdditions to your application descriptor XML file as described above.
• Recheck the format of your tester JSON file. If there are any errors or missing characters, Amazon Purchase tests will fail silently.

Now that you have Amazon In-App Purchases up and running in your app, you may want to explore these other native extension tutorials:

• Using in-app ratings with the RateBox native extension for Adobe AIR on iOS and Android
• Using native extensions in Adobe Flash Professional CS6
• Using the In-App Billing Adobe AIR native extension for Android
• Using the iOS In-App Purchase native extension for Adobe AIR
• Using the GoViral social networking extension for iOS
• Using the GameCenter Adobe AIR native extension for iOS
• Using the iAd Adobe AIR native extension for iOS
• More Native Extensions from Milkman Games