Migrating Your App to Amazon Underground

Warning: As of May 31, 2017, Amazon is no longer accepting new Underground app submissions. For more information, see Underground Actually Free Program FAQ – 2017 Update

Introduction

This page describes the required and recommended changes that you must make to an existing app before submitting the app to Amazon Underground, focusing on code and build changes. The heading for each section of this page specifies whether the described changes are required or recommended for your app.

Repackaging Your App (Required)

To migrate your app to Amazon Underground, re-build your APK as a new app with a unique Android package name. This package name must be distinct from the package name used in any other distribution channel, including Google or any non-Amazon Underground version in the Amazon Appstore. As a convention, Amazon recommends appending the string ".underground" to the original package name for the app. For example, "com.company.example.underground" would be the package name for the Amazon Underground version of "com.company.example."

Naming Custom Permissions for Android OS 5.0 (Lollipop) (Required for Custom Permissions)

To address security changes in Android OS 5.0 (Lollipop), any app that declares a custom permission for app-level resources must be signed with the same SSL certificate as all other apps declaring that same permission. If your app declares a custom permission, see https://forums.developer.amazon.com/articles/2706/android-security-changes-requires-uniquely-defined.html. If you do not make this change, your app's users could experience a version collision if they have both the Amazon Underground and non-Underground versions of your app installed at the same time.

Applying Amazon Underground Branding to Your App's Launcher Icon (Required)

Updating your launcher icon for Amazon Underground is part of the app migration process.

Creating Your Launcher Icons for Fire OS 5

For increased commonality with Android, the launcher on Fire OS 5 displays the app icon that you provide within your APK. This is a change from earlier versions of Fire OS, where the launcher used the app icon that you uploaded to the developer portal when submitting your app. See the Launcher Icon Guidelines for information about required icon resolution and dimensions.

Test your icon across the range of devices where you want your app to run, and make sure that the icon provides a clear and identifiable image that your customers recognize that positively represents your brand.

Applying the Amazon Underground Sash Overlay

To communicate your participation in Amazon Underground to your app's users, apply the Amazon Underground sash (shown below) to your app's launcher icon. Note that you only need to apply the sash to the launcher icon; you do not need to apply the sash to any other icons.

Below is a sample icon (192px) with the sash applied. (From the downloaded ZIP file, choose the appropriate-sized sash file for your launcher icon.)

Add the sash to your launcher icon as an overlay using a graphics editor. Include the sashed icon in the APK that you submit to the Amazon Underground program.

Download the sash PNG and PSD files.

Note: You must not change the sash PNG file in any way when you overlay it onto your launcher icon.

API Migration (Required for Apps Using Certain Amazon APIs)

If your app uses any of Amazon's Mobile SDK APIs, the following table summarizes the minimum required changes that you must make to your app for Amazon Underground:

API	App Changes Required?	Description of Minimum Changes
Amazon Drive	No	N/A
Amazon Device Messaging (ADM)	Yes	Create a new and separate API key for the Amazon Underground version of your app.
In-App Purchasing (IAP)	Yes	Re-create all of your individual IAP items with new SKUs as part of your app submission. In your app, update your code to reference the new SKUs for the Amazon Underground version.
Login with Amazon	Yes	Create a new and separate API key for the Amazon Underground version of your app.
Maps v2.0	No	N/A
Mobile Ads	Yes	Create a new and separate API key for the Amazon Underground version of your app.
Mobile Associates	Yes	Create a new and separate API key for the Amazon Underground version of your app.

The following sections give more details as to how to implement the changes required by these APIs to prepare your app for the Amazon Underground program.

In-App Purchasing (IAP) API: Modifying the IAP Items in Your App

If your existing app uses Amazon's In-App Purchasing (IAP) API, or your app contains IAP items that customers pay for on other sales platforms, you have the following options for migrating your IAP items to Amazon Underground:

Option 1: Re-create and re-submit the items to the Amazon Appstore using new SKUs for the Amazon Underground version of your app. Set each re-created item to its original IAP price; Amazon applies strikethrough pricing to your items to show that they are now free. You must also update your code base to use the new SKUs. See Submitting Your App and In-App Items for more information on submitting IAP items to the Amazon Appstore.

Note: If you are not already using Amazon's IAP API because your app uses a different in-app purchasing API, such as Google's IAB, you must implement Amazon's IAP API to use this option. If your app uses Google's In-App Billing, see Migrating from Google Play In-App Billing (IAB) v3.0 to Amazon In-App Purchasing (IAP) v2.0. (You may wish to consider Option 2 in this case.)
Option 2: Remove the IAP integration from your app, but provide an alternate mechanism for users to obtain IAP items for free. For example, build a "store" that does not actually make any IAP calls or have any IAP items on the backend but whose items can be "purchased" with the click of a button without paying anything. When developing ways to unlock IAP items, keep in mind that you will not be permitted to require users to watch ads to unlock IAP items.

Implementing Option 2 involves the following high-level tasks:

Remove the IAP SDK from your code.
Modify your purchase execution call to fulfill former IAP items to your users for free:
Add your own logic for what each former IAP button does, such as a "Buy" button. (This logic is handled by the IAP SDK for non-Amazon Underground apps.)
Fulfill the item to the customer.

Amazon encourages you to update the icons and strings for your IAP items for Amazon Underground to emphasize to users that they are now receiving these items for free. This helps to communicate to your users the value of those items that they are now receiving for free. See [App Design Modification Requirements and Guidelines for Amazon Underground][underground/app-design-and-modification-requirements-and-guidelines-for-amazon-underground] for more additional suggestions.

Mobile Ads API

If your app uses the Mobile Ads API, you must create a new and separate API key for the Amazon Underground version of your app so that your ad views are accurately tracked.

To view your Mobile Ads API key, log in to your developer account and click the Apps & Services tab, then click the Mobile Ads link. The Mobile Ads page displays the keys for each of your apps.

If your app uses any of these APIs, you must create a new and separate API key for the Amazon Underground version of your app for these APIs to work correctly. For Login with Amazon, you must create the Amazon Underground API key under the same security profile as the non-Amazon Underground key. This allows your customer consent to carry over from the non-Amazon Underground version and to ensure that the Amazon Underground version is authorized to request all the same scopes as the non-Amazon Underground version.

To view your ADM, Login with Amazon, or Mobile Associates API key:

Log in to your developer account.
Click the Apps & Services tab.
Click Security Profiles.
Click the security profile associated with your app.
Click the Android/Kindle Settings tab to view the key.

Updating Your App's Assets and Metadata (Recommended)

The Amazon Underground version of your app must retain the branding and identity of its non-Underground counterpart. If you have modified your app for Amazon Underground, call out these changes in your app's description as part of your new app submission package. For example, identify the Amazon Underground version of your app to aid user recognition.

Amazon recommends using the following types of unique assets and metadata for the Amazon Underground version of your apps:

In your app submission package, update your screenshot assets to show the Amazon Underground UI and gameplay for your app submission.
Also in your app submission package, update the short description to reflect the new value proposition of the app.
Make sure that your app's long and short description do not include any references to paying for the app or to IAP items with real currency. For example, if the non-Amazon Underground version of your app's descriptions mentions optional upgrades or entitlements that a user can purchase, do not copy-and-paste this part of the description to the Amazon Underground version of your app.
Within your app, any icons or strings related to IAP that contain pricing information should show the original price and communicate through strikethrough or other similar visual cue that these items are now free.

Last updated: Jul 13, 2017