Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Develop
Test
Publish
Monetize
Engage users
Device specifications
Resources
Skip to main content
After you Obtain Credentials to use Amazon Device Messaging (ADM) and set it up in your development environment, integrate ADM with your app. See Overview of ADM for a high-level overview of the process of adopting ADM in your app and server code.

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.
  1. Open your AndroidManifest.xml file and add the Amazon namespace:
  2. To declare the permissions necessary to support ADM, after the manifest element, add the permission and uses-permission elements.
  3. 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 specify android:required="false", your app must degrade gracefully if ADM is unavailable. In the application node of the manifest, add the uses-library element.
  4. Declare a broadcast receiver to handle the REGISTRATION and RECEIVE intents that ADM sends. ADM requires that the receiver be defined in the AndroidManifest.xml file, rather than programmatically. Immediately after uses-library add the following elements.
  5. After updating your AndroidManifest.xml file, you can confirm that the changes are correct for ADM by calling ADMManifest.checkManifestAuthoredProperly(). If you receive a java.lang.NoClassDefFoundError: com.amazon.device.messaging.ADM error, check your manifest to verify that you have added the uses-library element in the location specified in step 3.
The following code is a complete example of an AndroidManifest.xml file enabled for ADM.

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:
  1. Create a file called api_key.txt located inside your project’s assets folder. Placing the file in this specific directory is required.
  2. Insert your API key as the only data in this api_key.txt file.
For a release or “production” version of your app, if your app uses the Appstore SDK, you must create an additional API key for the release version of your app. If using the older IAP SDK v2.0 and you sign your app using your own certificate, you must also create an API key for the release version of your app. In contrast, if using the IAP SDK v2.0, or no in-app purchasing SDK at all, and you allow Amazon to sign your app on your behalf, you do not need to create an additional API key. For a summary, see .

Integrate ADM into your app’s main activity

The following code shows how to use the methods in the com.amazon.device.messaging.ADM class to:
  • Create an instance of an ADM context
  • Initiate registration with ADM for this instance of your app
You should run this code each time your app starts, for example, by placing it within your 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.
ClassDescription
com.amazon.device.messaging.ADMMessageHandlerJobBaseFor handling messages on the latest Fire devices
com.amazon.device.messaging.ADMMessageHandlerBaseFor handling messages on older Fire devices
com.amazon.device.messaging.ADMMessageReceiverFor forwarding messages to the appropriate message handling class
The broadcast receiver declared in your manifest both listens for intents and invokes your app when intents arrive. Your app communicates with the broadcast receiver via the following callback methods defined in the com.amazon.device.messaging.ADMMessageHandlerJobBase and com.amazon.device.messaging.ADMMessageHandlerBase classes:
Callback MethodDescription
onRegisteredCalled 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.
onUnregisteredCalled if your app instance becomes unregistered from ADM.
onRegistrationErrorCalled if your app’s ADM registration request fails for any reason, such as no Amazon user being signed in to the device.
onMessageCalled when the ADM client delivers a message to your app instance.
Your app must override these callbacks when you implement subclasses of com.amazon.device.messaging.ADMMessageHandlerJobBase, com.amazon.device.messaging.ADMMessageHandlerBase and com.amazon.device.messaging.ADMMessageReceiver, as shown in the following code examples:
  1. Check if the current device has been updated to support new ADM service.
  2. Create your receiver and service implementations.

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:
  1. Use code similar to the following to check for ADM.
  2. Add the following code to any of your code that requires the ADM library runtime.
  3. In your AndroidManifest.xml file, verify that the application element specifies:

Test ADM integration

You can confirm that your app is set up with ADM by sending a test notification to a device. See Send a Message for more information.
Last modified on October 30, 2024