Developer Console

App Tester User Guide

With App Tester, you can test Amazon In-App Purchasing (IAP) features before you publish your app to the Amazon Appstore. After you have downloaded, installed, and set up the App Tester tool, you can start testing purchasing features in your app.

If you have not already set up App Tester for your app, see Install and Configure App Tester.

Using App Tester

Amazon App Tester is a tool (previously used only by IAP) to simulate authorization with the Appstore. Download App Tester from the Amazon App Tester retail page or from the Amazon Appstore on your test device.

To use Amazon App Tester to test the license verification for your app:

  1. Connect your computer to either a Fire TV or Fire tablet through ADB. For details, see one of the following:

  2. Set your app in sandbox mode using the following command:

    adb shell setprop debug.amazon.sandboxmode debug
    

    Sandbox mode constrains calls that would normally go to the Appstore client to route to the Amazon App Tester app instead. Use this mode only for testing locally.

  3. Uninstall any existing version of Amazon App Tester, and then download and open the latest version on your Fire device.
  4. Open Amazon App Tester and go to Appstore SDK APIs > DRM API Response Settings > GetLicense API. You can set several license options:

    GetLicense API options are: Default, LICENSED, NOT_LICENSED, ERROR_VERIFICATION, ERROR_INVALID_LICENSING_KEYS, EXPIRED, and UNKNOWN_ERROR.
    DRM API Response Settings in App Tester
  5. Run your Fire TV or tablet app that contains DRM. Amazon App Tester simulates responses about the user's license status based on what you have selected in Amazon App Tester.

    To exit sandbox mode, run the following:

    adb shell setprop debug.amazon.sandboxmode none
    

Choose the Appstore SDK APIs

When you first launch App Tester, the landing page prompts you to choose the Appstore SDK APIs:

Appstore SDK APIs. App Tester Plugin module for In-App Purchasing and Digital Rights Management APIs.

Tap the Appstore SDK APIs prompt to begin. 

The list of available options. See the following numbered list for descriptions.

App Tester displays a list of navigation options for the Appstore SDK APIs:

  1. User Account Settings: Configure the user test accounts for your app.
  2. Subscription Purchase Settings: Configure conditions for subscription test cases, such as auto-renew and free trial.
  3. IAP API Response Settings: Configure the conditions and responses for your test cases.
  4. DRM API Response Settings: Configure license response for DRM test cases.
  5. Simple Sign-In API Response Settings: Configure conditions for Simple Sign-In test cases. For detailed testing instructions, see Test your App with App Tester in the Simple Sign-In documentation.
  6. Manage Sign-In links: Clear accounts linked with Simple Sign-in to reset test conditions. For details, see Managing Linked Accounts.
  7. Notification Settings: Enable or disable the notifications that are added to the notification drawer.
  8. Manage Transactions: Manage the active IAP transactions for your app.
  9. IAP Items in JSON File: View the data that you added to the App Tester from your JSON file in an easily human-readable format.

Manage users

You can sign a user in and out, change users, and change the marketplace associated with a user. These options facilitate testing different scenarios with different users in different marketplaces.

To access the user management screen, select Appstore SDK APIs from the App Tester landing page, then tap User Account Settings.

Available fields are: Status, Amazon User ID, User Marketplace, and LWAConsentStatus.

Sign in and out

To toggle the current user between being signed in and signed out, under Status tap the Logged in or Logged Out option.

Change the current user

App Tester provides three different test user accounts. Test users are named Amazon User 1, Amazon User 2, and Amazon User 3.

Select the user ID that you want to use for testing.

Change user marketplace for the current user

App Tester provides you with the ability to test your app in different international markets. To change the marketplace associated with the current user, look under User Marketplace and select a new market. The following markets are available:

  • US: United States of America
  • CA: Canada
  • MX: Mexico
  • BR: Brazil
  • GB: Great Britain
  • DE: Germany
  • FR: France
  • IT: Italy
  • ES: Spain
  • JP: Japan
  • IN: India
  • AU: Australia

If you've integrated your app with Quick Subscribe, you can set the consent status using the LWAConsentStatus option. To test your integration, set the response for consent status to CONSENTED or UNAVAILABLE. If set to CONSENTED, your app should call the Login with Amazon APIs to fetch customer data and automatically sign them in. If set to UNAVAILABLE, your app should fall back to the default sign-in experience.

Configure IAP API response settings

Use the IAP API Response Settings tab to set the conditions and responses for your test calls to the IAP API:

Available fields are: GetProductData API, GetPurchaseUpdates API, GetUserData API, Purchase API, and ModifySubscription API.

When specifying a response, Default in the following sections simply means to use the existing default settings. Default is not an available setting itself. If you explicitly select a value, such as SUCCESSFUL or FAILED, App Tester returns the selected value. For example, getProductData returns SUCCESSFUL if the JSON file contains the requested SKU. GetUserData returns FAILED if the user is set to Logged Out in User Account Settings.

The following table shows the available responses for the IAP APIs.

API Name Available Responses
GetProductData Default, SUCCESSFUL, FAILED
GetPurchaseUpdates Default, SUCCESSFUL, FAILED
GetUserData Default, SUCCESSFUL, FAILED
Purchase Default, SUCCESSFUL, FAILED, ALREADY_PURCHASED, INVALID_SKU
ModifySubscription Default, SUCCESSFUL, FAILED, INVALID_REQUEST, INVALID_SKU

Enable or disable your notifications

Use the Notifications Settings tab to enable or disable the notifications that are added to the system's notification drawer.

The following image shows the Notification Settings tab:

The following notification settings are available:

  • Purchase Updates Notifications: By default, Amazon sends a notification when an app loads a purchase dialog but has never called getPurchaseUpdates().  Amazon stops sending this notification after the app calls getPurchaseUpdates() once. Use the Purchase Updates Notifications setting to toggle whether Amazon ever sends this notification.

  • Notify Fulfillment Notifications: By default, Amazon sends a notification if a user makes a purchase and the item is not fulfilled within 30 seconds. Use Notify Fulfillment Notifications to toggle this notification on or off.

  • Reset Purchase Updates: Resets the state indicating whether or not getPurchaseUpdates() has been called.

Manage transactions

Use the Manage Transactions tab to view, cancel, and delete purchase transactions for the current user. Cancelling and deleting transactions are helpful tools when testing entitlements and subscriptions. This tab displays all transactions for the current user.

a list of transactions, each has the following fields: Item type, Sku, Receipt ID, Sold by, Purchased on, and Status.

The Manage Transactions tab contains the following information for each transaction:

  • Item Type: Type of product purchased. Valid values for IAP are CONSUMABLE, ENTITLEMENT, and SUBSCRIPTION.
  • Sku: Item SKU.
  • Receipt Id: Unique identifier for the transaction.
  • Sold By: App that sold the item.
  • Purchased On: Date that the item was purchased.
  • Status: Transaction status. Valid values are PURCHASED, CANCELED or PENDING. These App Tester values map to the IAP API values FULFILLED, UNAVAILABLE, and PENDING respectively.

When an app calls PurchasingService.notifyFulfillment(receiptId, FulfillmentResult.FULFILLED, the receipt shows up in the Manage Transactions section with status: FULFILLED.

 From the Manage Transactions tab, you can perform the following tasks:

  • Refresh the list of transactions for the current user.
  • Delete all transactions for the current user.
  • Cancel an individual transaction.
  • Delete an individual transaction.

View the IAP Items in your JSON file

To provide an easy way to view the IAP items in the JSON file that you configured in Installing and Configuring the App Tester, tap the IAP Items in JSON File tab. If you have correctly added a valid JSON file, the App Tester parses and displays the contents of the file under this tab.

If you have not correctly added a valid JSON file, this tab either displays an error message or specifies that the JSON file does not exist.

Simulate your users' experience

In addition to providing responses to API requests, App Tester can display purchase flow dialogs, just like a live, published app does. The benefit of this feature is that the dialogs can help you to evaluate the user experience for your app's purchase process.

App Tester displays two interstitial dialogs for each Purchase Request. The first dialog is a detail screen that shows the purchase price and other details, as shown in the following IAP example:

Options are: Cancel and Get Item.
App detail screen

The second dialog is a "thank you" screen that a user must manually close by tapping the "X" button in the upper right-hand corner, as shown in the following IAP example:

Thank you! Your order is complete.
Thank you screen

Logging

App Tester uses the Logcat tool to capture details about your app's transactions and other API interactions. To use Logcat to view the logs generated while testing your app:

  1. Connect the Android device with your app and App Tester to a computer running Android Debug Bridge (ADB).
  2. Search for the tag "AmazonAppTester" to view the App Tester log entries.

If you are using the Eclipse DDMS development environment, you can filter App Tester generated log entries by entering tag:AmazonAppTester into the filter text area in the Logcat tab.

Using App Tester to test your DRM

To test out DRM on a device, you will need to install Amazon App Tester. Amazon App Tester is required to test the DRM functionality in your app.

Amazon App Tester provides a tab called "DRM API Response Settings" that allows you to simulate responses for different license statuses.

To use Amazon App Tester to test the license verification for your app, add the following drm.ResponseReceiver to your app's AndroidManifest.xml file. If your app targets Android 12 or higher, you must explicitly set android:exported to true in the MainActivity and ResponseReceiver as shown in the following example:

 <application>
 ...
    <activity android:label="@string/app_name" android:name="com.amazon.sample.drm.MainActivity" 
                android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>

    <receiver android:name = "com.amazon.device.drm.ResponseReceiver" android:exported="true" 
                android:permission = "com.amazon.drm.Permission.NOTIFY" >
        <intent-filter>
            <action android:name = "com.amazon.drm.NOTIFY" />
        </intent-filter>
    </receiver>
 ...
 </application>

More details are also provided in the DRM Sample App.


Last updated: Dec 19, 2023