Amazon Device Messaging, a free service that allows you to send cloud-based push notifications to Kindle Fire customers, is now out of Beta and is in general availability.

You can use ADM to send encrypted real-time notification to update users on breaking news or let them know that a new game task is available for them to complete. You can also use ADM for instant messaging functionality or social networking notifications within your app.

Messaging Overview

• Deployment. We have documentation, sample code, tools, and FAQs to help you integrate ADM. Adding ADM to your app is easy. You obtain your ADM credentials and key (remember, this is an encrypted message), include the ADM library as an external JAR file, update your manifest, store your key as an asset, and implement your broadcast receiver. (we have sample code that shows this). To send a message, your server needs the app registration ID and a security token. You can find more implementation details here.
• Simple. ADM delivers message data to your app on the device, and your app can decide what to do on receipt of that data like download content or display a notice. Your message should be no greater than 6KB in size and sent in the form of JSONObject key:value pairs.
• Delivery. Messages expiration is one week by default, but can be configured to persist for one month if required. ADM will wake up the device to deliver messages, so messages can be sent and received during off-peak hours when the device is likely to be asleep. We use Amazon Web Services as a backend for this service, so we can scale up quickly and reliably.
• Compatibility. ADM is supported on Kindle Fire HD 8.9" 4G, Kindle Fire HD 8.9", Kindle Fire HD 7", and Kindle Fire (2nd Generation) devices.
• Free. Enough said.

Getting Started

Get started with Amazon Device Messaging by downloading the SDK here and reviewing our documentation, sample code, and FAQs. Submit your ADM-enabled app through the Amazon Amazon Mobile App Distribution Portal today!

Feedback from the Beta

During the ADM beta, we had big and small companies try the service, and we got international developer feedback as well. Here is some of the feedback we received:

From Wooga, a social game developer based in Berlin:

“The decision to integrate Amazon Device Messaging into Diamond Dash was a cinch – it is a clear win”, said Soenke Bullerdiek, Senior Manager Strategic Platform Partnerships, from Wooga, “Even better, it was easy to enable and only took a few days of work to start sending push notifications to our users.”

From Gameloft, a world-wide game developer based in the U.S.:

“We decided to use Amazon Device Messaging as a new way to engage our Oregon Trail American Settlers customers on Kindle Fire.  The documentation and sample code was easy to understand for our studios.” Baudouin Corman, VP Americas Gameloft.

Overview

This article discusses how mobile apps can use Amazon Web Services to communicate with users via e-mail, short message service (SMS), and other communication channels. The sample code presented here uses Amazon Simple Notification Service and Amazon Simple Queue Service. Amazon Simple Notification Service (Amazon SNS) makes it easy to set up, manage, and send notifications from mobile apps and have these notifications delivered immediately to any users who have chosen to subscribe to them. Amazon SNS provides a highly scalable, flexible, and cost-effective method to implement such notification systems.

Amazon Simple Queue Service (Amazon SQS), also discussed here, offers a reliable, highly scalable, hosted queue for storing messages. The types of messages supported by Amazon SQS include—but aren't limited to—the notification messages sent from Amazon SNS.

Together, Amazon SNS and Amazon SQS enable developers to create apps that can message large numbers of users in multiple formats quickly and easily.

The sample app described here demostrates how mobile apps can message their users through Amazon SNS and Amazon SQS. The sample demonstrates how to use Amazon SNS to create a topic, subscribe users to that topic, and publish notifications to the topic. Subscribers to the topic can receive their notifications via e-mail, SMS, or an Amazon SQS queue. Amazon SQS and Amazon SNS can also be used to create other types of communication systems not shown here.

This article shows sample code but the complete sample code and project files are included in the AWS SDK for Android. A link to the SDK is available at the end of this article.

To use the AWS SDK for Android, you will need AWS credentials, that is, an Access Key ID and Secret Access Key. If you haven't already signed up for Amazon Web Services (AWS), you will need to do that first to get your credentials. You can sign up for AWS here. After you sign up, you can retrieve your credentials at this page.

Creating Amazon SQS and Amazon SNS Clients

Making requests to Amazon SNS and Amazon SQS requires creating a client for each service. The code below shows how to create a client:

AWSCredentials credentials =      new BasicAWSCredentials( Constants.ACCESS_KEY_ID, Constants.SECRET_KEY );		AmazonSNSClient snsClient = new AmazonSNSClient( credentials );AmazonSQSClient sqsClient = new AmazonSQSClient( credentials );

Topic Creation

Amazon SNS uses topics to route notifications from publishers to subscribers. The term publisher refers to an app that sends notifications; the term subscriber refers to an entity, such as a user, that receives notifications. Topics provide a junction point for publishers and subscribers to communicate with each other. Once a topic is created, subscribers can be added to the topic and receive notifications/messages. The DisplayName attribute is added to a topic to allow notifications to be sent via SMS.

CreateTopicRequest ctr = new CreateTopicRequest( Constants.TOPIC_NAME );CreateTopicResult result = snsClient.createTopic( ctr );	        SetTopicAttributesRequest tar      = new SetTopicAttributesRequest( result.getTopicArn(), "DisplayName", "MessageBoard" );this.snsClient.setTopicAttributes( tar );  

Subscribing to Topics

In order for notifications sent to a topic to be received, you have to subscribe an endpoint to that topic. The endpoint corresponds to a recipient. An endpoint is an e-mail address, SMS number, web server, or Amazon SQS queue. If you are using an Amazon SQS queue, it needs to be configured to receive notification messages from Amazon SNS. Once you subscribe an endpoint to a topic and the subscription is confirmed, the endpoint will receive all messages published to that topic.

SubscribeRequest sr = new SubscribeRequest( this.topicARN, "email", email );this.snsClient.subscribe( sr );

Listing a Topic's Subscribers

Listing the subscribers for a topic provides the endpoint and corresponding protocol for each subscriber who receives notification via that topic. The protocol for an endpoint depends on the type of endpoint. For example, endpoints that are e-mail addresses have a protocol of SMTP.

ListSubscriptionsByTopicRequest ls = new ListSubscriptionsByTopicRequest( this.topicARN );ListSubscriptionsByTopicResult response = this.snsClient.listSubscriptionsByTopic( ls );return response.getSubscriptions();

Publishing Notifications

Publishers send notifications to topics. Once a new notification is published, Amazon SNS attempts to deliver that notification to every endpoint that is subscribed to the topic.

PublishRequest pr = new PublishRequest( this.topicARN, message );this.snsClient.publish( pr );	

Unsubscribing from Topics

Unsubscribing removes the endpoint from the topic and stops notifications from being received.

UnsubscribeRequest unsubscribeRequest = new UnsubscribeRequest( subscriptionArn );this.snsClient.unsubscribe( unsubscribeRequest );

Creating a Queue

The first task in using Amazon SQS is to create a queue. Once a queue is created it can be subscribed as an endpoint to an Amazon SNS topic.

CreateQueueRequest cqr = new CreateQueueRequest( Constants.QUEUE_NAME );CreateQueueResult result = this.sqsClient.createQueue( cqr );return result.getQueueUrl();

Subscribing a Queue to a Topic

Here's how to subscribe a queue to a topic. However, for the queue to receive messages, you must also add a policy to the queue. See below.

String queueArn = this.createMessageQueue();		SubscribeRequest request = new SubscribeRequest();request.withEndpoint( queueArn ).withProtocol( "sqs" ).withTopicArn( this.topicARN );		this.snsClient.subscribe( request );

Adding a policy to a Queue

In order for a queue to receive messages from a topic, the queue must have a policy object that specifies that the topic has sqs:SendMessage permission for the queue. For further details see the Amazon SNS FAQ. For more information about queue policies see the Amazon SQS documentation. Once the policy object is created it can be attached to the queue as follows:

HashMap attributes = new HashMap();attributes.put("Policy", generateSqsPolicyForTopic( queueArn, this.topicARN ) );this.sqsClient.setQueueAttributes(new SetQueueAttributesRequest( queueUrl, attributes ) );

Receiving Messages from a Queue

Now that a message is in the queue, you can receive it, which requires getting it from the queue. When requesting to get a message from the queue, you can't specify which message to get. Instead, you simply specify the maximum number of messages you want to get (up to 10), and Amazon SQS returns up to that maximum number. Because Amazon SQS is a distributed system and the particular queue we're working with here has very few messages in it, the response to the receive request might be empty. Therefore, you should rerun the sample until you get the message. You should design your own app so that it continues to poll the queue until it gets one or more messages.

ReceiveMessageRequest rmr = new ReceiveMessageRequest( this.queueUrl );rmr.setMaxNumberOfMessages( 10 );rmr.setVisibilityTimeout( 30 );ReceiveMessageResult result = this.sqsClient.receiveMessage( rmr );

Delete Messages from a Queue

Amazon SQS doesn't automatically delete a message after returning it to the app. By default, it keeps the message to protect against the case where the receiving app fails or loses its connection. In these cases, a different app—or perhaps a new instance of the same app— might attempt to get the message.

To delete the message, you must send a separate request. You specify which message to delete by providing the receipt handle that Amazon SQS returned when you received the message. You can delete only one message per call. Deleting the message acknowledges that you've successfully received and processed it.

DeleteMessageRequest request      = new DeleteMessageRequest( this.queueUrl, message.getReceiptHandle() );this.sqsClient.deleteMessage( request );

References

A sample app that includes this code is provided with the SDK. The download link can be found on the following page:

• AWS SDK for Android

For more information about using AWS credentials with mobile apps see the following article:

• Authenticating Users of AWS Mobile Applications with a Token Vending Machine

Questions?

Please feel free to ask questions or provide comments in the Mobile Development Forum.