Home > Devices > Fire Phone

Using the API Simulator Tool

Introduction

The Fire Phone SDK includes an API Simulator tool for developers who do not have access to a Fire phone. The API Simulator enables you to test basic app features, such as side panels and app widgets (hero widgets) using a regular Android device or emulator.

This document explains how to configure your app for use with the API Simulator and test your app's use of Foundation Controls and the Home API on a stock Android device or emulator. The solution presented here does not allow for testing of other Fire phone APIs, such as Firefly or the Dynamic Perspective controls and sensor APIs.

Prerequisites

To test your app that uses the side panel or app widget on a stock Android device or emulator, you must have:

  • A stock Android device or emulator running Android API level 17, 18, or 19. Fire runs on API level 17, so we recommend your device or emulator run API level 17 as well.
  • The Fire Phone SDK. The SDK includes code that enables you to test side panel and app widget behavior on a stock Android device or emulator.
  • An app that uses only the side panel and app widget (hero widget) APIs. The testing setup does not support any other APIs, including other Amazon APIs. If your app makes use of other Amazon APIs, you’ll need to make sure those APIs are not exercised while testing the side panel or app widget portions of your app. The API Simulator does support testing side panels and app widgets at the same time.

Recommended Android Virtual Device Settings

When running your app, the characteristics of your stock Android device or emulator should match those of the Fire phone as closely as possible, otherwise the results may not be accurate. Fire specifications are available in the Fire Phone SDK at <ADT>/sdk/add-ons/addon-new_device_sdk_addon-amazon-17/devguides/specs where <ADT> is your Android Development Tools folder.

If you are using an emulator, you should create a custom Android Virtual Device with the characteristics shown in the following screenshot.

Overview of Testing

The following sections describe the steps you need to take to test your app that uses side panels or an app widget with the API Simulator.

Side Panel Apps

To test your app that uses side panels on a stock Android device or emulator, use the following steps:

  1. Add the Amazon namespace to the <manifest> tag in the AndroidManifest.xml.
  2. Change the <uses-library> tag to an <amazon:enable-feature> tag in the AndroidManifest.xml.
  3. Add AmazonSupport.jar to your app.
  4. Integrate AmazonSupport.jar with your app.
  5. Install AmazonPlatform.apk on your stock Android device or emulator.
  6. Compile, install, and run your app on the stock Android device or emulator.
  7. Prepare your app for submission to the Amazon Appstore.
App Widget

To test your app widget on a stock Android device or emulator, use the following steps:

  1. Add the Amazon namespace to the <manifest> tag in the AndroidManifest.xml.
  2. Change the <uses-library> tag to an <amazon:enable-feature> tag in the AndroidManifest.xml.
  3. Add AmazonSupport.jar to your app.
  4. Integrate AmazonSupport.jar with your app.
  5. Install AmazonPlatform.apk on your stock Android device or emulator.
  6. Install HomeSimulator.apk on your stock Android device or emulator.
  7. Compile, install, and run your app on the stock Android device or emulator.
  8. Launch HomeSimulator.apk on your stock Android device or emulator to view the results.
  9. Prepare your app for submission to the Amazon Appstore.

Add the Amazon Namespace to the <manifest> Tag

Modify the <manifest> tag to include the Amazon namespace.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:amazon="http://schemas.amazon.com/apk/res/android"
          ...>
  ...
</manifest>

 

Change <uses-library> to <amazon:enable-feature> in the AndroidManifest.xml

When compiling for a physical Fire phone, your manifest should include a <uses-library> tag to specify that your app requires the Foundation Controls (EAC) library for side panels or the home library for the app widget. However, when compiling for stock Android devices and emulators, you cannot use a <uses-library> tag because those devices do not have the Foundation Controls (EAC) library or home library available to them. Instead, replace the <uses-library> tag with an <amazon:enable-feature> tag within the body of the <application> tag as shown in the example below. The value of android:name should be eaclibrary for side panels and com.amazon.device.home for the app widget.

Side Panel Example

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
  <application ...>
    <!-- Use "eaclibrary" for the Foundation Controls (EAC) library and
         "com.amazon.device.home" for app widgets -->
    <amazon:enable-feature android:name="eaclibrary"
                           android:required="true" />
    ...
  </application>
  ...
</manifest>

App Widget Example

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
  <application ...>
    <!-- Use "eaclibrary" for  the Foundation Controls (EAC) library and
         "com.amazon.device.home" for app widgets -->
    <amazon:enable-feature android:name="com.amazon.device.home"
                           android:required="true" />
    ...
  </application>
  ...
</manifest>

Integrate AmazonSupport.jar with Your App

Copy <ADT>/add-ons/addon-fire_phone_sdk_addon-amazon-17/tools/api_simulator/AmazonSupport.jar to the libs folder of your app's source tree to statically link it with your app's code. <ADT> is your Android Development Tools folder.

AmazonSupport.jar contains code that loads the classes from the Foundation Controls (EAC) library and the app widget (hero widget) classes and resources onto the stock Android device or emulator. In order for AmazonSupport.jar to work successfully, it needs to be loaded before your app performs any actions. To make this happen, you modify your app's AndroidManifest.xml to tell the Android launcher to launch an activity within AmazonSupport.jar. This activity loads  the Foundation Controls (EAC) library and app widget (hero widget) classes and resources, then launches your app's main activity, which is also specified in the AndroidManifest.xml.

The specific changes needed to integrate AmazonSupport.jar with your app are as follows:

  • Modify the <activity> tag by changing the android:name to com.amazon.sdk.support.AmazonSupportActivityPrototype.
  • Add a <meta-data> tag within the body of the <activity> tag with an android:name attribute whose value is com.amazon.callback.activity and an android:value attribute whose value is the fully qualified class name of your app's main activity.
  • Add a second <activity> tag with an android:name attribute whose value is the fully qualified class name of your app's main activity.
  • The AmazonSupport.jar activity needs to be the activity triggered by the android.intent.action.MAIN and android.intent.category.LAUNCHER intents as shown in the following example manifest. Other activities should not respond to these intents.

Here is an example AndroidManifest.xml showing the changes needed to integrate AmazonSupport.jar with your app:

Side Panel Example

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:amazon="http://schemas.amazon.com/apk/res/android"
          ...>
  <application ...>
    <!-- Use "eaclibrary" for the Foundation Controls (EAC) library and
         "com.amazon.device.home" for app widgets -->
    <amazon:enable-feature android:name="eaclibrary"
                           android:required="true" />

    <activity android:name="com.amazon.sdk.support.AmazonSupportActivityPrototype">
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
      <!-- enter fully qualified class name for android:value -->
      <meta-data android:name="com.amazon.callback.activity"
                 android:value="com.yourapp.MainActivity" />
    </activity>

    <!-- enter fully qualified class name for android:name --> 
    <activity android:name="com.yourapp.MainActivity" />
  </application>
  ...
</manifest>

 

App Widget Example

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:amazon="http://schemas.amazon.com/apk/res/android"
          ...>
  <application ...>
    <!-- Use "eaclibrary" for the Foundation Controls (EAC) library and
         "com.amazon.device.home" for app widgets -->
    <amazon:enable-feature android:name="com.amazon.device.home"
                           android:required="true" />

    <activity android:name="com.amazon.sdk.support.AmazonSupportActivityPrototype">
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
      <!-- enter fully qualified class name for android:value -->
      <meta-data android:name="com.amazon.callback.activity"
                 android:value="com.yourapp.MainActivity" />
    </activity>

    <!-- enter fully qualified class name for android:name -->
    <activity android:name="com.yourapp.MainActivity" />
  </application>
  ...
</manifest>

 

Install AmazonPlatform.apk on Your Stock Android Device or Emulator

Install <ADT>/sdk/add-ons/addon-new_device_sdk_addon-amazon-17/tools/emulator/AmazonPlatform.apk on the stock Android device or emulator that you are using for testing. <ADT> is your Android Development Tools folder. You can use the Android Debug Bridge (adb) to install the .apk by typing the following command at a command prompt or in a terminal window:

adb install <ADT>/sdk/add-ons/addon-new_device_sdk_addon-amazon-17/tools/emulator/AmazonPlatform.apk

 

Install HomeSimulator.apk on Your Stock Android Device or Emulator

Install <ADT>/sdk/add-ons/addon-fire_phone_sdk_addon-amazon-17/tools/api_simulator/HomeSimulator.apk on the stock Android device or emulator that you are using for testing. <ADT> is your Android Development Tools folder. You can use the Android Debug Bridge (adb) to install the .apk by typing the following command at a command prompt or in a terminal window:

adb install <ADT>/sdk/add-ons/addon-fire_phone_sdk_addon-amazon-17/tools/api_simulator/HomeSimulator.apk

 

Prepare Your App for Submission to the Amazon Appstore

Once you have tested the Fire features of your app, you need to remove the <amazon:enable-feature> tag and replace it with the <uses-library> tag before recompiling your app. To make this change, simply substitute uses-library for amazon:enable-feature as shown in the following examples.

Side Panel Example

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
  ...
  <application ...>
    <!-- android:required="true" is optional with uses-library -->
    <!-- if omitted, it is implied -->
    <uses-library android:name="eaclibrary"
                  android:required="true" />
    ...
  </application>
</manifest>

App Widget Example

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
  ...
  <application ...>
    <!-- android:required="true" is optional with uses-library -->
    <!-- if omitted, it is implied -->
    <uses-library android:name="com.amazon.device.home"
                  android:required="true" />
    ...
  </application>
</manifest>

You should leave AmazonSupport.jar in place and should not further modify AndroidManifest.xml. This is to minimize the number of changes made post-testing to reduce the likelihood of introducing a bug. Your app will still call on code in AmazonSupport.jar, but when it is running on Fire, it does nothing and simply launches your app's main activity.

Known Limitations

There are some known limitations when using the emulator for testing:

  • The system displays all text in the Roboto font.
  • Switches, TimePickers, NumberPickers, and Dialogs will most likely not look correct.
  • APIs other than the side panel, app widget, and standard Android are not supported. If you use other Amazon APIs in your app, you must ensure they are not exercised while testing the side panel or app widget portion of your code.
  • Motion gestures (one-handed shortcuts) are not supported. Side panels must be accessed by touch screen swipes.
  • The carousel and hero icon are not emulated when you test app widget functionality.
  • Swiping works on the API Simulator but you need to make contact at the very edge of the screen.