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.
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:
Your server sends a message containing JSON data to ADM servers.
ADM servers send the message to the ADM client on the device on which your app is installed.
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.
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.
ID/Credential
Obtained by...
Obtained from...
Used by...
Uniqueness
Registration ID
A specific instance of your app
ADM servers, via the ADM client on the device on which the app instance is installed.
Your servers, ADM servers, and the ADM client, to route messages to the correct instance of your app.
Unique per install of the app, on a given device, for a specific user. If the registration ID becomes invalid or inactive, messages directed to the registration ID fail and ADM returns an appropriate error message. For example, if the user uninstalls then re-installs your app, you might receive a new registration ID.
You are visitor 01402503 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.
