Install and Configure App Tester

App Tester allows you to unit test the In-App Purchasing (IAP) functionality of your app in sandbox mode before you submit the app for publication.

You download App Tester onto the same device as your app, or you can use the Vega Virtual Device (VVD). The App Tester simulates the production environment.

You can run IAP-related test cases on your app, and App Tester generates API responses that you configure using a JSON file.

App Tester prerequisites

Your development and testing environment must meet the following prerequisites to run test cases with App Tester:

• Your development environment allows logging via VDA and logcat. Here are more details about how to Connect using VDA, as well as the VDA commands.
• Your app implements the Vega IAP API method calls.
• You have no SDK Tester on the device. SDK Tester is not compatible with App Tester or with the Vega IAP SDK.
• Add this information to the manifest.toml file.

Copy code Copied to clipboard.

[wants]
# ... other wants

[[wants.service]]
id = "com.amazon.iap.tester.service" # This is required for tester (Sandbox mode)

[[wants.module]]
id = "/com.amazonappstore.iap.tester@IIAPTesterUI"

[needs]

[[needs.module]]
id = "/com.amazon.kepler.appstore.iap.purchase.core@IAppstoreIAPPurchaseCoreService"

# ...

We recommend that you create one or more purchasable items for your app in the Amazon Appstore. This allows you to easily create the required JSON file.

Download App Tester

The App Tester is a free app which can be downloaded below.

For React Native 0.72

The following downloads are for the current release.

0.72 Vega IAP App Tester 0.21 - x86_64

0.72 Vega IAP App Tester 0.21 - Mac M-series

0.72 Vega IAP App Tester 0.21 - Vega Fire Stick

Install App Tester on your device

Here’s how you set it up on your device:

• For installing and launching the IAP App Tester follow the instructions on how to Run Your App on Vega Virtual Device or Fire TV Stick.

The following is a quick reference.

Installing on a Fire TV device

To push .vpkg file

kepler exec vda push <path to .vpkg file>/<appname.vpkg> /tmp

To access your Fire TV

kepler exec vda shell

To install App Tester on your device

vpm install /tmp/<appname.vpkg>

To access your Fire TV

kepler exec vda shell

To uninstall App Tester on your device

vpm uninstall <package_id>

Installing on a Vega Virtual Device

To start VVD

kepler virtual-device start

To install the app on VVD

kepler run-kepler  <path to .vpkg file>/<appname.vpkg> com.amazonappstore.iap.tester.ui -d VirtualDevice

To access VVD

kepler exec vda shell

To launch App Tester on your device

vlcm launch-app pkg://com.amazonappstore.iap.tester.ui

To terminate App Tester on your device

vlcm terminate-app -f -p com.amazonappstore.iap.tester

You can learn more about vpm and vlcm in our Package and Lifecycle Manager documentation.

To install and run your app on VVD, see Install and Configure App Tester.

Create a JSON data file

The App Tester responds to API calls using data stored in a JavaScript Object Notation (JSON) file. The file contains purchase data for the IAP items.

You can automatically create the JSON file through the Apps & Games Developer Portal.

1. In a web browser, go to the your app's page on the Apps & Games Developer Portal.
2. Add your IAP purchasable items to your app, if you have not already done so.
3. Click the link to download your JSON Data File.
4. Name the downloaded file "amazon.sdktester.json".

5. Push the SKU JSON file into the device.

   1. To create this directory on the device

   Copy code Copied to clipboard.

   kepler exec vda shell mkdir /tmp/scratch/com.amazonappstore.iap.tester/
   

   2. To push to the created directory

   Copy code Copied to clipboard.

   kepler exec vda push <amazon.sdktester.json file> /tmp/
   

   Copy code Copied to clipboard.

   kepler exec vda shell cp /tmp/<amazon.sdktester.json> /tmp/scratch/com.amazonappstore.iap.tester/
   

To create a JSON data file for VVD

1. To create this directory on the device

kepler exec vda shell mkdir /tmp/scratch/com.amazonappstore.iap.tester/

2. To push to the created directory

kepler device copy-to -s <path of amazon.sdktester.json> --destination /tmp/scratch/com.amazonappstore.iap.tester

If you open the downloaded JSON file, note that the general file format is as follows.

Copy code Copied to clipboard.

 {
  Item_ID_1:{Item_1_Description},
  Item_ID_2:{Item_2_Description},
  .
  .
  .
  Item_ID_n:{Item_n_Description}
  }

The actual item description definition varies by item type. The order of the items in the JSON file is not significant. Note the comma "," between description definitions.

File format and example: IAP consumable and entitlement items

Consumable and Entitlement IAP Item Descriptions have the same format. The itemType property indicates whether the item is ENTITLED or CONSUMABLE. Every purchasable item is associated with a unique identifier called an SKU.

Copy code Copied to clipboard.

"your_item_SKU":{
  "itemType": "ENTITLED|CONSUMABLE",
  "price": price,
  "title": "item_title",
  "description": "item_description",
  "smallIconUrl": "full_url_for_small_icon"
  }

The following example shows a consumable and an entitlement item:

Copy code Copied to clipboard.

{
"com.amazon.sample.iap.consumables.orange":{
  "itemType": "CONSUMABLE",
  "price": 10.00,
  "title": "Orange",
  "description": "An orange",
  "smallIconUrl": "http://www.amazon.com/orange.jpg"
  },

"com.amazon.sample.iap.entitlements.level2":{
  "itemType": "ENTITLED",
  "price": 10.00,
  "title": "Level 2",
  "description": "An entitlement to play level 2"
  }
}

File format and example: IAP subscription item

Subscription items are different from other types of items you can purchase. Every purchasable item is associated with an identifier called an SKU that identifies it as unique. When a subscription is purchased, there are two SKUs involved. One, the "parent SKU", describes what the subscription is for (such as a magazine title). The other SKU is the "terms SKU", which describes the terms (price, length) of the subscription. The terms SKU is what actually gets purchased by a customer.

Since the terms SKU is the purchasable item, the JSON IAP Item Description is for that item. However, the description must also contain a reference to the Parent SKU. Therefore, subscription item types include an additional property: subscriptionParent.

Copy code Copied to clipboard.

"your_terms_SKU":{
  "itemType": "SUBSCRIPTION",
  "price": price,
  "title": item_title,
  "description": item_description,
  "smallIconUrl": "http://www.amazon.com/kindle.jpg",
  "subscriptionParent": "your_parent_SKU"
  }

An example of a subscription item description follows below (note the subscription parent SKU).

Copy code Copied to clipboard.

{
  "com.amazon.sample.iap.subscription.mymagazine.silver": {
      "description": "Monthly Subscription to My Magazine Silver",
      "title": "Silver month",
      "itemType": "SUBSCRIPTION",
      "price": 50.0,
      "subscriptionBase": "com.amazon.subs.base",
      "subscriptionParent": "com.amazon.subs.silver",
      "term": "Monthly",
      "freeTrialPeriod": "Monthly",
  },
  "com.amazon.sample.iap.subscription.mymagazine.gold": {
      "description": "Monthly Subscription to My Magazine Gold",
      "title": "Gold month",
      "itemType": "SUBSCRIPTION",
      "price": 80.0,
      "term": "Monthly",
      "subscriptionBase": "com.amazon.subs.base",
      "subscriptionParent": "com.amazon.subs.gold"
  }
}

Verify your IAP items

You can easily review the contents of the JSON file. From the App Tester main menu, tap the IAP Items in JSON File option to display a human-readable list of the item data in the JSON file.

Next step: Use App Tester

Last updated: Sep 30, 2025