Menu
Amazon Simple Notification Service
Developer Guide (API Version 2010-03-31)

Getting Started with Amazon Device Messaging

Amazon Device Messaging (ADM) is a service that enables you to send push notification messages to Kindle Fire apps. This section describes how to obtain the ADM prerequisites and send a push notification message using Amazon SNS and ADM.

ADM Prerequisites

To send push notifications to a Kindle Fire app using Amazon SNS and ADM, you need the following:

  • Kindle Fire app with the ADM service enabled

  • Client ID and client secret

  • API key

  • Registration ID

If you already have these prerequisites, then you can send a push notification message to a Kindle Fire app using either the Amazon SNS console or the Amazon SNS API. For more information about using the Amazon SNS console, see Using Amazon SNS Mobile Push. For more information about using the Amazon SNS API, see Step 5: Sending a Push Notification Message to a Kindle Fire app using Amazon SNS and ADM

Step 1: Create a Kindle Fire App with the ADM Service Enabled

To send a push notification message to a Kindle Fire app, you must have an Amazon developer account, set up your development environment, created a Kindle Fire app with ADM enabled, and registered the app with ADM. For more information, see Integrating Your App with ADM.

To create a Kindle Fire app

  1. Create an Amazon developer account by following the instructions at Create an Account.

  2. Set up your development environment for developing mobile apps for Kindle Fire tablets. For more information, see Setting Up Your Development Environment.

  3. Create a Kindle Fire app. For more information, see Creating Your First Kindle Fire App.

    Note

    If you do not already have a Kindle Fire app registered with ADM, then you can use the sample Kindle Fire app provided by AWS as a template to get started. For more information, see Step 4: Obtain a Registration ID.

  4. On the Amazon App Distribution Portal, click Apps and Services, click the name of your Kindle Fire app, and then click Device Messaging.

  5. Verify that ADM is enabled for the app. If your app is not listed on the Amazon App Distribution Portal, then add it and enable ADM.

Step 2: Obtain a Client ID and Client Secret

ADM uses a client ID and client secret to verify your server's identity. For more information, Obtaining ADM Credentials.

To obtain a client ID and client secret

  1. On the Amazon App Distribution Portal, click Apps and Services, click the name of your Kindle Fire app, and then click Security Profile. You should see a security profile associated with your app. If not, click Security Profiles to create a new security profile.

  2. Click View Security Profile. Make note of the client ID and client secret.

Step 3: Obtain an API Key

ADM uses an API key to verify your app's identity.

Note

An API key is required to use ADM with pre-release or test apps. However, it is not required with a release or production version of your app when you allow Amazon to sign your app on your behalf.

To obtain an API key

Step 4: Obtain a Registration ID

The following steps show how to use the sample Kindle Fire app provided by AWS to obtain a registration ID from ADM. You can use this sample Kindle Fire app as an example to help you get started with Amazon SNS push notifications. The sample app requires that you have included the ADM JAR file, amazon-device-messaging-1.0.1.jar in your development environment. For more information, see Setting Up ADM.

To obtain a registration ID from ADM for your app

  1. Download and unzip the snsmobilepush.zip file.

  2. Import the KindleMobilePushApp folder into your IDE. In Eclipse, click File, Import, expand the Android folder, click Existing Android Code Into Workspace, click Next, browse to the folder KindleMobilePushApp, click OK, and then click Finish.

    After the sample Kindle Fire app has been imported into your IDE, you need to add the API key for your Kindle Fire app to the strings.xml file, which is included in the sample Kindle Fire app.

  3. Add the API key to the strings.xml file. In your IDE you will find the file included in the values folder, which is a subfolder of res. You add the string to the following:

    Copy
    <string name="api_key"></string>
  4. Run the app to see the registration ID as output to the Android logging system. If you are using Eclipse with the Android ADT plug-in, you can see the registration ID in the LogCat display window. For example, the output containing the registration ID will look similar to the following:

    Copy
    amzn1.adm-registration.v2.Example...1cwWJUvgkcPPYcaXCpPWmG3Bqn-wiqIEzp5zZ7y_jsM0PKPxKhddCzx6paEsyay9Zn3D4wNUJb8m6HXrBf9dqaEw

You should now have the necessary information from ADM (client ID, client secret, API key, and registration ID) to send push notification messages to your mobile endpoint. You can now send a push notification message to the Kindle Fire app on your device by either using the Amazon SNS console or the Amazon SNS API. To use the Amazon SNS console, see Using Amazon SNS Mobile Push. To use the Amazon SNS API, see Step 5: Sending a Push Notification Message to a Kindle Fire app using Amazon SNS and ADM.

Step 5: Sending a Push Notification Message to a Kindle Fire app using Amazon SNS and ADM

This section describes how to use the prerequisite information to send a push notification message to your Kindle Fire app using Amazon SNS and ADM. You add the gathered prerequisite information to the AWS sample file SNSMobilePush.java, which is included in the snsmobilepush.zip file.

Note

The following steps use the Eclipse Java IDE. The steps assume you have installed the AWS SDK for Java and you have the AWS security credentials for your AWS account. For more information, see AWS SDK for Java. For more information about credentials, see How Do I Get Security Credentials? in the AWS General Reference.

To add the sample to Eclipse

  1. Create a new Java project in Eclipse (File | New | Java Project).

  2. Import the SNSSamples folder to the top-level directory of the newly created Java project. In Eclipse, right-click the name of the Java project and then click Import, expand General, click File System, click Next, browse to the SNSSamples folder, click OK, and then click Finish.

  3. In the SNSSamples\src\com\amazonaws\sns\samples\mobilepush folder, open the AwsCredentials.properties file and add your AWS security credentials.

To add the AWS SDK for Java to the Build Path

  1. Right-click the Java project folder, click Build Path, and then click Configure Build Path...

  2. Click the Libraries tab, and then click Add Library....

  3. Click AWS SDK for Java, click Next, and then click Finish.

To add the prerequisite information to SNSMobilePush.java

  1. In the SNSSamples\src\com\amazonaws\sns\samples\mobilepush folder, open SNSMobilePush.java in Eclipse.

  2. Uncomment sample.demoKindleAppNotification();. It should look similar to the following:

    Copy
    SNSMobilePush sample = new SNSMobilePush(sns); // TODO: Uncomment the services you wish to use. // sample.demoAndroidAppNotification(); sample.demoKindleAppNotification(); // sample.demoAppleAppNotification(); // sample.demoAppleSandboxAppNotification(); // sample.demoBaiduAppNotification(); // sample.demoWNSAppNotification(); // sample.demoMPNSAppNotification();
  3. Locate the demoKindleAppNotification method and enter the registration ID you received from ADM for the value of the registration ID string. For example, it should look similar to the following:

    Copy
    String registrationId = = "amzn1.adm-registration.v2.Example...1cwWJUvgkcPPYcaXCpPWmG3Bqn-wiqIEzp5zZ7y_jsM0PKPxKhddCzx6paEsyay9Zn3D4wNUJb8m6HXrBf9dqaEw";
  4. Enter the client ID for your app. For example, it should look similar to the following:

    Copy
    String clientId = "amzn1.application-oa2-client.EXAMPLE7423654b79fc9f062fEXAMPLE";
  5. Enter the client secret for your app. For example, it should look similar to the following:

    Copy
    String clientSecret = "EXAMPLE01658e75ceb7bf9f71939647b1aa105c1c8eaccabaf7d41f68EXAMPLE";
  6. Enter a name for your app. App names must be made up of only uppercase and lowercase ASCII letters, numbers, underscores, hyphens, and periods, and must be between 1 and 256 characters long. For example, it should look similar to the following:

    Copy
    String applicationName = "admpushapp";
  7. Run the Java application. You should see output similar to the following in the output window of your IDE:

    Copy
    =========================================== Getting Started with Amazon SNS =========================================== {PlatformApplicationArn: arn:aws:sns:us-west-2:111122223333:app/ADM/mypushappname} {EndpointArn: arn:aws:sns:us-west-2:111122223333:endpoint/ADM/mypushappname/97e9ced9-f136-3893-9d60-775467eafebb} {"ADM": "{ \"data\": { \"message\": \"ENTER YOUR MESSAGE\" } }"} Published. MessageId=b35fb4bz-b503-4e37-83d4-feu4218d6da6

    On your Kindle Fire device, you should see a push notification message appear within the Kindle Fire app.