Testing notes
When testing your app’s use of ADM, note the following:- First-generation Kindle Fire tablets do not support ADM.
-
Second-generation Kindle Fire tablets must be running the following system versions to support ADM. To see the system version, go to Settings > Device > About.
- Kindle Fire HD 8.9” - System Version 8.3.0 or later
- Kindle Fire HD 7” - System Version 7.3.0 or later
- Kindle Fire (2nd Generation) - System Version 10.3.0 or later. On second-generation tablets, your corporate firewall may block network access for ADM. Your app must be able to communicate with servers outside your corporate network using UDP on one of the following ports: 49317, 33434, 40317
- Other system versions of Fire tablets and Fire TV devices all support ADM.
Update your app manifest
Updating your AndroidManifest.xml file is the first step in receiving messages sent via ADM. You must make the following changes to your existing file.-
Open your AndroidManifest.xml file and add the Amazon namespace:
-
To declare the permissions necessary to support ADM, after the
manifestelement, add thepermissionanduses-permissionelements. -
Explicitly enable ADM and declare whether your app requires ADM (
android:required="true") or can work without ADM being present (android:required="false"). If you specifyandroid:required="false", your app must degrade gracefully if ADM is unavailable. In theapplicationnode of the manifest, add theuses-libraryelement. -
Declare a broadcast receiver to handle the
REGISTRATIONandRECEIVEintents that ADM sends. ADM requires that the receiver be defined in the AndroidManifest.xml file, rather than programmatically. Immediately afteruses-libraryadd the following elements. -
After updating your AndroidManifest.xml file, you can confirm that the changes are correct for ADM by calling
ADMManifest.checkManifestAuthoredProperly(). If you receive ajava.lang.NoClassDefFoundError: com.amazon.device.messaging.ADMerror, check your manifest to verify that you have added theuses-libraryelement in the location specified in step 3.
Store your API key as an asset
To enable your app to receive messages, your app must contain a valid API key. Obtain Credentials describes the process of creating an API key, and Overview of ADM discusses the API key in more detail. For a pre-release or “debug” version of your app, you must create an API key and store it in your project. To add the API key to your app:- Create a file called
api_key.txtlocated inside your project’s assets folder. Placing the file in this specific directory is required. - Insert your API key as the only data in this
api_key.txtfile.
Integrate ADM into your app’s main activity
The following code shows how to use the methods in thecom.amazon.device.messaging.ADM class to:
- Create an instance of an ADM context
- Initiate registration with ADM for this instance of your app
onCreate() method. If your app is already registered, getRegistrationId() returns the registration ID for this instance of the app, and startRegister() isn’t called. If this is the first startup of the app on a given device or if a previous registration failed, this code begins the registration process.
Implement handling for registration and messages
ADM has three classes that you must extend. Refer to the following table to understand the function of each. You can also review the ADM API reference.| Class | Description |
|---|---|
com.amazon.device.messaging.ADMMessageHandlerJobBase | For handling messages on the latest Fire devices |
com.amazon.device.messaging.ADMMessageHandlerBase | For handling messages on older Fire devices |
com.amazon.device.messaging.ADMMessageReceiver | For forwarding messages to the appropriate message handling class |
com.amazon.device.messaging.ADMMessageHandlerJobBase and com.amazon.device.messaging.ADMMessageHandlerBase classes:
| Callback Method | Description |
|---|---|
onRegistered | Called when the registration ID for the app instance is ready. Your app must transmit this registration ID to your server. Doing so enables your server to send messages to the app instance. |
onUnregistered | Called if your app instance becomes unregistered from ADM. |
onRegistrationError | Called if your app’s ADM registration request fails for any reason, such as no Amazon user being signed in to the device. |
onMessage | Called when the ADM client delivers a message to your app instance. |
com.amazon.device.messaging.ADMMessageHandlerJobBase, com.amazon.device.messaging.ADMMessageHandlerBase and com.amazon.device.messaging.ADMMessageReceiver, as shown in the following code examples:
-
Check if the current device has been updated to support new ADM service.
-
Create your receiver and service implementations.
Version for backward compatibility on older/non-updated devices
Version for backward compatibility on older/non-updated devices
Gracefully degrade if ADM is unavailable
In your manifest file, you declare whether your app can (android:required="false") or cannot (android:required="true") work without ADM. If you specify android:required="false", your app must degrade gracefully if ADM is unavailable.
Designing your app to accommodate the absence of ADM allows you to build a single APK that can be installed and run on devices that may or may not include ADM.
To modify your app to gracefully degrade:
-
Use code similar to the following to check for ADM.
-
Add the following code to any of your code that requires the ADM library runtime.
-
In your AndroidManifest.xml file, verify that the application element specifies:

