Archive

Showing posts tagged with ADM

The Cordova Push Notifications Plugin is a project that lets hybrid web app developers create apps that respond to custom push notifications from services such as the Apple Push Notification Service (APNS), Google Cloud Messaging (GCM) and most recently Amazon Device Messaging (ADM). This enables hybrid web apps to be notified when an online service has information for it - such as a personal message, sports score or appointment - even if the app is not currently running.

If you're unfamiliar with Amazon Device Messaging, it's a simple, efficient and free messaging service from Amazon that lets developers send push notifications from the cloud to Kindle Fire devices, helping app creators more deeply engage with their customers by keeping them up to date and involved.

Create Security Profile to obtain ADM credentials for your app.Note: For development, you can use the MD5 signature of the debug apk created by Cordova build process found in <project_path>/platforms/amazon-fireos/ant-build.

You will need to make note of the OAuth Credentials (Client ID and Client Secret) to be used on your notifications server and the API Key to be used in your client app. These can be found on the Security Profile Management pages in the areas marked in green below:

Below is a graphic which shows a general overview of the authentication process and how your client app and your server to authenticate and register with the ADM Server:

Install Push Notifications Plugin

Once you have created an initial Cordova app for the Amazon Fire OS platform, use the standard plugin command from your project directory to install the Push Notifications Plugin.

cordova plugin add https://github.com/phonegap-build/PushPlugin.git

This will download the plugin and install it in your app's project directory. There will be a new folder called <com.phonegap.plugins.PushPlugin> inside your project's plugin directory. This folder contains: the source files for the plugin, an Example directory that has a sample web app you can use to receive ADM notifications on the client, and a Node.js script you can use to send notifications, simulating what a server would normally do.

Before you can start testing notifications, you will need to follow the steps below to download and install the ADM support libraries and add the proper credentials to your project.

Install Amazon Device Messaging Library

The push notifications plugin needs the support files found in the ADM API. Follow these steps to download the SDK and install the library files in your Cordova project:

Create a folder called ext_libs in <project_path>/platforms/amazon-fireos folder.

Copy amazon-device-messaging-x.x.x.jar into the <project_path>/platforms/amazon-fireos/ext_libs

Create a new text file called ant.properties in the <project_path>/platforms/amazon-fireos folder, and add a java.compiler.classpath entry pointing at the ADM library. For example:

java.compiler.classpath=./ext_libs/amazon-device-messaging-1.0.1.jar

Create a new text file called api_key.txt in the <project_path>/platforms/amazon-fireos/assets folder, and copy the API Key you obtained in the Credentials section above. Note: Be careful not to add any extra spaces to the text file.

Create Sample App

Here's a basic web app that can be used to test receiving notifications on the client. Create new index.html and index.js files in your project's www directory and copy the markup/code below.

The index.html page is simply a container for the messages to be displayed on the device:

The handleDeviceReady method will use the pushNotification object to register the client with the ADM Server. This requires that the api_key.txt file contains the correct information.

The Registration ID that is returned to the client is used by your server to send notifications to the correct device/app combination. The ID is very long, so there's a link to email the ID to yourself to be used in testing.

The notification event has a flag to tell your app whether it was in the foreground, background or not started when the notification arrived.

The ADM notification event contains a payload object consisting of arbitrary fields populated by your server. In this example, the server will send a message, timestamp and URL, but each app can be different.

If there are errors with authentication or other issues such as connectivity problems, the app should log to the screen any error messages sent to your app.

Once you have your client app ready, use Cordova's command line to install the app on your test device (usually using the "cordova run" command). If you have set up everything correctly, the app will start, authenticate with the ADM Server and display the Registration ID unique to your device/app to be used by your notifications server.

Test ADM Notifications

Normally, you will have a dedicated server which sends app notifications via the ADM Server, using the Registration ID to uniquely identify each instance of your app running on a specific device. Your app will be responsible for getting the Registration ID from each registered device to your server.

For testing purposes, we are instead going to use the pushADM.js Node script found in the <project_path>/plugins/com.phonegap.plugins.PushPlugin/Example/server folder. This script acts in place of your server, authenticating with Amazon and then pushing notifications to the ADM Servers to be delivered to your app. (Node is a prerequisite for Cordova, so you should already have it installed on your system.)

Before we can use the script, we need to add in your OAuth Credentials and Registration ID. Here is a snippet from the top part of the test script that you will be editing:

Copy the OAuth credentials - Client ID and Client Secret - you obtained in the Credentials section above into the CLIENT_ID and CLIENT_SECRET variables.

Copy one or more Registration IDs from a registered app into the REGISTRATION_IDS array. Note: You can fill this var with IDs from multiple devices for testing. Using the sample app above, you can email the Registration ID to yourself and then copy/paste it into the test script.

Optionally edit the payload object with custom values to be sent to your app.

Run the pushADM.js script from a command line using Node:

node pushADM.js

The result on the command line should be a series of log messages which shows the script authenticating with the ADM Server and then sending a message. The app running on your Kindle Fire should then instantly show the message if it is in the foreground, or add a notification alert to the top bar if it is in the background or not running. You can run this script as many times as you need to test your app.

Here is what the of the sample web app above looks like after receiving a notification:

Summary

The steps above should give you a good start towards implementing ADM push notifications into your app. Once you have your app working, it will be very easy to customize the notification payload as you need to create compelling new apps and services for your customers.

If you have trouble, please make sure to check out the links below for information and support:

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.

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.