Home > Services & APIs > Engage > Device Messaging

Understanding Amazon Device Messaging

Introduction

Introduction

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.

This guide provides an overview of how you work with ADM on both the client side and the server side of your app.

Architecture

The ADM architecture is:

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 may 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 may 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.

Figure 1 shows how a message is passed from your server to an instance of your app.

Figure 1: Sending a message with ADM

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 [Integrating Your App with ADM][adm-integrating-your-app]. Your servers use the registration ID to direct messages to the correct device/user. Note that if the user uninstalls then re-installs your app on the same device, your app’s registration ID may 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 [Obtaining ADM Credentials][adm-obtaining-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 [Obtaining ADM Credentials][adm-obtaining-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 [Requesting an Access Token][adm-requesting-access-token] for more information.

Table 1: ADM Identifiers & 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 may receive a new registration ID.
API Key You, for your app Amazon; see [Obtaining ADM Credentials][adm-obtaining-credentials] for details on this process. The ADM Client, to confirm your app's identity. Different versions of your app (for example a debug version and a production version) each require their own API Key.
OAuth Client Credentials You, for your servers Amazon; see [Obtaining ADM Credentials][adm-obtaining-credentials] for details on this process. Your servers and ADM Servers, to identify your servers for the purpose of obtaining an access token. Unique to your app.
Access Token Your servers ADM Servers, in response to your request call. Your servers and ADM Servers, to verify your ability to send a message. Each of your servers only uses one access token at a time. You must obtain a new access token when an old one expires.

Next Steps

To use ADM, you must:

  • Add the ADM API package to your development environment. See [Setting Up ADM][adm-setting-up].
  • Get your API Key and client credentials from Amazon. See [Obtaining ADM Credentials][adm-obtaining-credentials].
  • Integrate your app with ADM. See [Integrating Your App with ADM][adm-integrating-your-app].
  • Implement message handling in your app.
  • Integrate your servers with ADM. See [Requesting an Access Token][adm-requesting-access-token] and [Sending a Message][adm-sending-message].
  • Test your app.
  • Submit your app to the Amazon Apps & Games Developer Portal.