Migrating Your App to HAQM Underground

Warning: As of May 31, 2017, HAQM 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 HAQM 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 HAQM 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-HAQM Underground version in the HAQM Appstore. As a convention, HAQM 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 HAQM 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 http://forums.developer.haqm.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 HAQM Underground and non-Underground versions of your app installed at the same time.

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

Updating your launcher icon for HAQM 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 HAQM Underground Sash Overlay

To communicate your participation in HAQM Underground to your app's users, apply the HAQM 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 HAQM 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 HAQM APIs)

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

API	App Changes Required?	Description of Minimum Changes
HAQM Drive	No	N/A
HAQM Device Messaging (ADM)	Yes	Create a new and separate API key for the HAQM 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 HAQM Underground version.
Login with HAQM	Yes	Create a new and separate API key for the HAQM Underground version of your app.
Maps v2.0	No	N/A
Mobile Ads	Yes	Create a new and separate API key for the HAQM Underground version of your app.
Mobile Associates	Yes	Create a new and separate API key for the HAQM 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 HAQM Underground program.

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

If your existing app uses HAQM'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 HAQM Underground:

Option 1: Re-create and re-submit the items to the HAQM Appstore using new SKUs for the HAQM Underground version of your app. Set each re-created item to its original IAP price; HAQM 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 HAQM Appstore.

Note: If you are not already using HAQM's IAP API because your app uses a different in-app purchasing API, such as Google's IAB, you must implement HAQM'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 HAQM 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-HAQM Underground apps.)
Fulfill the item to the customer.

HAQM encourages you to update the icons and strings for your IAP items for HAQM 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 HAQM 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 HAQM 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 HAQM Underground version of your app for these APIs to work correctly. For Login with HAQM, you must create the HAQM Underground API key under the same security profile as the non-HAQM Underground key. This allows your customer consent to carry over from the non-HAQM Underground version and to ensure that the HAQM Underground version is authorized to request all the same scopes as the non-HAQM Underground version.

To view your ADM, Login with HAQM, 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 HAQM Underground version of your app must retain the branding and identity of its non-Underground counterpart. If you have modified your app for HAQM Underground, call out these changes in your app's description as part of your new app submission package. For example, identify the HAQM Underground version of your app to aid user recognition.

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

In your app submission package, update your screenshot assets to show the HAQM 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-HAQM 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 HAQM 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