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
Amazon Device Messaging (ADM) lets you send messages to Amazon devices that run your app, so you can keep users up to date and involved. Whether you’re giving a user a game update or letting them know that a message from their buddy has arrived, ADM helps you stay in touch. If you have an existing Android app and it uses Google Firebase Cloud Messaging (FCM), follow the device messaging migration guide, or consider using the A3L Messaging SDK. Note that ADM is not supported on Kindle Fire (1st Generation) devices.

Download the Amazon Device Messaging (ADM) SDK

You can download the ADM SDK here: The download includes API reference documentation and an example app with ADM integrated. Note that by downloading the ADM SDK, you agree to our Program Materials License Agreement. Extract the SDK contents to a location of your choice.

ADM architecture

The architecture of ADM follows several key principles:
  • Protected. As a sender, your servers are verified via the OAuth 2.0 client credentials flow. As your message is passed to a device, the endpoint connections are authenticated and protected with industry-standard SSL encryption. And ADM uses Android permissions on the device to direct the message to your app only.
  • Simple. ADM is a transport mechanism, delivering message data to your app. ADM does not provide any built-in user interface or other handling for the data. For example, upon receiving a message, your app might wake up the device, post a notification, display a custom user interface, or sync data.
  • Flexible. ADM doesn’t process the data you send in any way. Your message is only required to be no greater than 6KB in size and to send data in the form of JSONObject key:value pairs.
The following characteristics also apply to messages you send via ADM:
  • ADM wakes up the device to deliver messages.
  • ADM makes no guarantees about delivery or the order of messages.
  • Due to varying network conditions, messages might be delivered more than once. Your app must be able to handle instances of duplicate messages.
  • Messages expire. The default expiration time is one week; the maximum is one month. You can also set a custom expiration time for a message when you send it. When a message expires, ADM might remove the message from the delivery queue.

Roles and responsibilities

There are four components involved in sending a message with ADM, two of which you control. Your servers
  • Identify themselves to ADM servers with an access token.
  • Send messages to ADM servers for delivery to your app.
ADM servers
  • Use an access token to validate your servers’ identity.
  • Deliver messages from your servers to the ADM client on the device.
ADM client
  • Handles your app’s registration process with ADM servers.
  • Receives messages from ADM servers and passes them to your app.
Your app
  • Registers with the ADM client to receive messages from your servers.
  • Receives incoming messages from the ADM client and handles those messages.

Message flow

At a high level, the delivery flow for a message that you send by ADM is as follows:
  1. Your server sends a message containing JSON data to ADM servers.
  2. ADM servers send the message to the ADM client on the device on which your app is installed.
  3. The ADM client obtains the JSON message data and passes it to your app as a set of extras attached to an Android Intent object.
understanding-adm

Message passage from your server to an instance of your app

Identification and security

When working with ADM, you use the following elements to identify your servers, your app, and the destinations for your messages. Each of these works together to help ensure that your data belongs to you alone.
  • Registration ID. A registration ID identifies a unique instance of your app, running on a specific device, registered to a specific user. When it is first installed on a given device, your app requests a registration ID from ADM, as described in Integrate Your App. Your servers use the registration ID to direct messages to the correct device/user. If the user uninstalls then re-installs your app on the same device, your app’s registration ID might change.
  • API key. An API key is metadata that ADM uses to differentiate between your app and other apps on a given device. The API key is assigned to you by Amazon; see Obtain Credentials for details.
  • OAuth Client Credentials. Your client credentials are two pieces of data: a “client identifier” and a “client secret” value. These credentials are assigned to you by Amazon; see Obtain Credentials for details. Your servers use both pieces of these credentials in their requests to obtain access tokens.
  • Access Token. An access token is short-lived metadata that confirms your server’s identity to ADM, so that you can send messages. Your servers obtain their access tokens by providing your client credentials in a request call to ADM Servers. When one of your servers requests an access token, the response to that request includes both the access token and its lifespan in seconds. See Request an Access Token for more information.

ADM identifiers and credentials

The following table lists ADM identifiers and credentials.
Last modified on May 18, 2022