How to Migrate to Amazon In-App Purchasing From Google's

Welcome. If you're new to the Amazon Appstore, check out our recent introductory guide, How to Submit Your App to the Amazon Appstore. In today's episode, I'll walk you through the benefits and requirements of Amazon's In-App Purchasing (IAP). Specifically, I'll describe how those of you with Google Play apps that leverage Google's IAB can easily migrate their applications to work with Amazon IAP.

Benefits of the Amazon Appstore

Before we dive in, I just want to recap the benefits of the Amazon Appstore. 

When you add your app to the Amazon Appstore, it's visible to Android and Fire users in more than 200 countries, and developers can now list their PC, Mac and HTML5-based web apps as well as Android apps. By submitting your app, web app or game to the program, you can grow your business and revenue.

According to Statista, there are currently more than 600,000 apps in the Amazon Appstore.

In addition to today's tutorial, you can find a breadth of helpful information at Amazon's Developer portal.

Moving From Google Play to the Amazon App Store

If your Android app is already in the Google Play store, it's even easier to join the Amazon Appstore. Amazon reports that over 85% of Android apps just work on Kindle Fire with no additional development necessary. Here's a short video guiding you through the process, Moving from Google Play to the Amazon Appstore (video):

But if you use Google's IAB, you'll need to switch over, and I'll show you how.

Before I go further, I want to encourage you to reach out with any questions you may have about the tutorial. Post them in the comments below or to me @lookahead_io on Twitter. Let us know if you'd like to see more tutorials about the Amazon Appstore or AWS in general.

Understanding the In-App Purchasing API

With the In-App Purchasing API, you can enable compelling feature sets and scenarios such as:

• Creating a "freemium" model for your app, where the app itself is free but you charge a premium for advanced services or functionality


• Allowing customers to purchase in-app currency directly within your app experience


• Allowing customers to subscribe to content available within your app


• Making content available for purchase to be viewed within your app

The Amazon In-App Purchasing API allows your app to present, process, and fulfill purchases of digital content and subscriptions within your app experience. To enable this feature set, simply implement the In-App Purchasing API as detailed in the implementation section below:

The In-App Purchasing API is designed to encapsulate the complexity behind the purchase process while providing a fully featured API. The In-App Purchasing API will handle the details about purchase flow, payment processing, providing a receipt to your app, and managing rights to the purchasable content.

Once you build a storefront, you can use the In-App Purchasing API to vend purchasable items:

There are three kinds of purchasable items:

• 
  Consumables: content that does not require an entitlement or access rights to use, can be purchased multiple times by a customer, is available only on the device it is purchased from, and does not require any type of entitlement check to use.


• 
  Entitlements: content that requires an entitlement or access rights to use, can be purchased only once by a customer, and is available on all compatible devices registered to the customer's account.


• 
  Subscriptions: content that requires an entitlement or access rights to use, is bound by a period of time, auto-renews, and is available on all eligible devices registered to the customer's Amazon account

The Amazon Client

The Amazon Client is an integral part of the In-App Purchasing API. Once you initiate a purchase, the Amazon Client surfaces and presents an Amazon-branded user interface to complete the transaction. This flow is used by all apps that choose to employ the In-App Purchasing API.

If the Amazon Client is not installed or is otherwise not available, a message is surfaced to the customer indicating the appropriate course of action.

The Amazon Client presents the user interface for all aspects of the purchase workflow. It provides the logic to display the purchasable item, perform the 1-Click purchase itself, and handle any preconditions or error scenarios that arise.

Providing a link directly to the Amazon Client from within your app is an effective tool for promoting your apps. This type of link is referred to as a deep link. More information on deep linking can be found in the documentation.

Separation of Responsibilities

When developing with the Amazon In-App Purchasing API, it is important to understand which parts of the purchase flow the app must implement, and which parts are handled by the Amazon Client.

The Amazon Client will take care of the purchase workflow, starting when the customer decides to purchase an item and ending when the store provides the application a receipt for the purchase (or other status in the case of a failed purchase). Developers should not provide purchase dialogs, transaction timeout logic, or "Thank You" dialogs. These are all provided by the Amazon Client. Please see the User Interface Guidelines and Conventions section for more details.

In the event a purchase is unsuccessful, the Amazon Client will present messaging to the customer; your app should not message the customer. For example, if the customer does not have a valid credit card on file, the client redirects the customer to a page where they can update their payment information. You should not provide a confirmation or other interstitial dialog to the customer regarding the purchase flow.

Content Sources

Your app can leverage the In-App Purchasing API in a variety of ways. How you choose to implement it can affect how you build your app. No matter how you choose to implement it, there are two basic flows available to you: locally available content and deliverable content.

Locally Available Content

Locally available content is unlocked or otherwise made available to the customer upon purchase. Under this model, your app already has everything it needs for the customer to use the purchasable item except the right to use it. You can use all three types of purchasable items with this model.

Your app should contain the unique identifiers for each purchasable item (SKUs), the ability to present a catalog to the customer, and logic within the app to unlock the purchasable item upon successful transaction.

Deliverable Content

Deliverable content allows you to make new content available to the customer. Under this model, your app will download the new content from your servers and make it available to the customer.

Your app should contain the unique identifiers for each purchasable item (SKUs), the ability to present a catalog to the customer, and logic within the app to download, persist, and make available the downloaded content upon successful transaction.

Remember: IAP v1.0 Has Been Deprecated

In July 2014, Amazon released the In-App Purchasing (IAP) v2.0 API, which includes several important updates. As of 30 April 2016, Amazon deprecated IAP v1.0 for new and updated app submissions. While this deprecation does not affect apps that were already live in the Amazon Appstore, any apps submitted as either a new or updated app after 11 May 2016 will need to use IAP v2.0. 

• To learn more about this deprecation, see the blog post Migrate Your IAP v1.0 Apps to v2.0.


• For step-by-step instructions on how to migrate your app, see Migrating from IAP v1.0 to IAP v2.0.

Migrating From Google Play In-App Billing (IAB) v3.0 to Amazon In-App Purchasing (IAP) v2.0

Now, let's discuss the differences between Google Play’s In-App Billing (IAB) and Amazon’s In-app Purchasing (IAP) and give a high-level description of how to adapt your app to use both API sets.

What Are IAB and IAP?

Google Play’s In-App Billing feature allows users to make purchases of virtual items directly from your app. For example, a user can purchase additional levels to a game that he or she is playing. 

Amazon’s In-App Purchasing is the equivalent feature for Amazon APIs. If you have an app that uses Google Play’s In-App Billing feature, you can easily modify your code to use Amazon’s equivalent In-App Purchasing feature. Both API sets have similar functionality with some differences in naming and terminology.

Requirements for the Amazon Appstore and Amazon Devices

If you will be submitting an app that implement’s Google Play’s IAB to the Amazon Appstore to be made available to run on Amazon devices, such as Fire tablets, your app will need to implement Amazon’s IAP for in-app purchases. Google Play’s IAB will not work on Amazon devices.

Amazon IAP v2.0 vs. Google Play IAB v3.0

Feature Comparison

The table below shows a comparison between Amazon’s IAP API and Google Play’s IAB API:

Google Play’s Managed Objects vs. Amazon’s Consumables and Entitlements

While Google Play’s IAB and Amazon’s IAP both let your customers make the same types of in-app purchases, Google Play and Amazon use different terminology for their purchase types. The following table notes the Google Play equivalent for each Amazon purchase type:

As you can see, Google Play’s IAB treats all non-subscription purchases similarly; an item is purchased, then consumed by a user. Once an item has been consumed, the item is provisioned in the app, and the consumption is recorded. For items that are likely to be one-time purchases, such as unlocking new game levels, you have the option as a developer of treating the item as a consumable or non-consumable and introducing logic to ensure that the purchase of that item only occurs once. 

With Amazon’s IAP, these one-time purchases are separated by design from purchases, such as extra lives, that app users might purchase again and again.

Porting Your Code

Let's walk you through porting an App from Google Play’s IAB API to the Amazon IAP API:

1. Configure your AndroidManifest.xml file to support Amazon’s IAP.


2. In your app, implement logic to mediate between IAB and IAP.


3. Add and implement the Amazon IAP API.


4. Test your app.

Configuring Your AndroidManifest.xml File

Configure your AndroidManifest.xml file to define the IAP Response Receiver for your app. The IAP Response Receiver ensures that the intent communication from the Amazon Client is intercepted by your app. Note that if you are supporting both Google Play’s IAB and Amazon’s IAP, you do not need to remove elements related to IAB; they will simply be ignored by IAP.

In your AndroidManifest.xml file, add the appropriate <receiver> tag for the IAP ResponseReceiver:

<application>
...
    <receiver android:name="com.amazon.inapp.iap.ResponseReceiver">
        <intent-filter>
            <action android:name="com.amazon.inapp.purchasing.NOTIFY" android:permission="com.amazon.inapp.purchasing.Permission.NOTIFY">
        </action></intent-filter>
    </receiver>
...
</application>

Implementing Logic to Mediate Between IAB and IAP

You can use the same code base for your app, regardless of where your app is hosted. Just add logic to your app to determine whether the app was downloaded from the Amazon Appstore or from Google Play. Depending on where the user downloaded the app, execute the appropriate methods for either IAP or IAB.

The following example code determines whether a package was installed from Google Play or the Amazon Appstore:

PackageManager pkgManager = context.getPackageManager();

 String installerPackageName = pkgManager.getInstallerPackageName(context.getPackageName());

 if(installerPackageName.startsWith("com.amazon")) {
 // Amazon
 } else if ("com.android.vending".equals(installerPackageName)) {
 // Google Play
 }

Adding and Implementing the Amazon IAP API

For the most part, Amazon’s IAP works similarly to Google Play’s IAB. When you create the path in your code to implement the IAP API, you should be able to use a similar logic flow to IAB, but will need to account for different class and method names.

The following table maps the most frequently used IAP methods to their IAB equivalents:

Note that Amazon’s notifyFulfillment() call and Google Play’s consumePurchase() call correlate with each other somewhat. Calling consumePurchase()on a managed item for IAB will return the item’s state to “unpurchased”, essentially converting it to a consumable. After that, the receipt will no longer appear in the response from subsequent calls to getPurchases(). Amazon will return the receipts for consumable items in calls to getPurchaseUpdates() until the app calls notifyFulfillment().

For more information about the classes and methods of IAP, see the In-App Purchasing API Reference v2.0.

Testing Your App

Download and install the App Tester tool to test your IAP v2.0-integrated app. This tool can also test Mobile Associates APIs, if your app uses those, as well. Follow the instructions and links in Testing In-App Purchasing (IAP) to install and use App Tester.

After testing your app locally, you can use the Live App Testing service to beta test your app in a live production environment with a select group of users.

In Closing

I hope you've enjoyed today's guide as well as our earlier How to Submit Your App to the Amazon Appstore episode. Please let us know which Amazon Appstore areas you'd like to see covered in more detail. You can post them in the comments below or reach me on Twitter @lookahead_io. 

If you liked this tutorial, please be sure to check out my series on building a startup with PHP, and keep up with my Envato Tuts+ instructor page to see some of my other tutorials and series.

Related Links

• 
  How to Submit Your App to the Amazon Appstore (Envato Tuts+)
  
  


• Amazon Developer Console


• Submitting Your Apps to the Amazon App Store


• Amazon Appstore Publishing Frequently Asked Questions


• Understanding In-App Purchasing API (IAP v1.0)


• Migrating from Google Play In-App Billing (IAB) v3.0 to Amazon In-App Purchasing (IAP) v2.0