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.

You can find the plugin, and complete documentation on the Cordova PushPlugin Github repository, but here are the basics on getting started using the plugin for Amazon Fire OS.

Overview

Amazon Device Messaging works similarly to the other push notification services and has three main parts involved in the process:

• Your server sends notifications (messages, updates, scores, etc.) to the ADM Servers to be routed to the client apps.
• ADM Servers queue and route notifications to client apps.
• Your  app receives the notification on a device.

The Cordova Push Notifications Plugin allows your hybrid web app to use JavaScript to register with the ADM Server and receive notification events when sent from your server.

Please note that ADM only works with Fire OS devices and the Cordova Amazon Fire OS platform target. For more information about setting up a Fire OS Cordova project, please see our earlier blog post,  Building Higher Performance Cordova-based Fire OS Apps By Implementing Amazon WebView Support.

ADM Credentials

In order for your server to send notifications to your app, both the server and app, need to be authenticated/registered with the ADM Server:

1. Create a sample Cordova app for the Amazon Fire OS platform so you have the app name, package name and the debug build ready.
2. Create a developer account on the Amazon Developer Portal if you don't already have one
3. Fill out the New App Submission form and turn Device Messaging switch to ON.
4. 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:

1. Download the Amazon Mobile App SDK and unzip.
2. Create a folder called ext_libs in <project_path>/platforms/amazon-fireos folder.
3. Copy amazon-device-messaging-x.x.x.jar into the <project_path>/platforms/amazon-fireos/ext_libs
4. 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
   

5. 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:

index.html:

<!DOCTYPE html>
<html>
<head>
	<title>ADM Test</title>
</head>
<body>
	<h1>ADM Test</h1>
	<pre id="container" style="word-wrap:break-word"></pre>
	<script src="cordova.js"></script>
	<script src="index.js"></script>
</body>
</html>

var container = document.getElementById("container");
var pushNotification;

document.addEventListener("deviceready", handleDeviceReady, true);

function handleDeviceReady(){

    pushNotification = window.plugins.pushNotification;
    pushNotification.register( handleSuccess, handleError, {"ecb":"handleNotification"});

}

function handleNotification(e) {

    log("**** EVENT RECEIVED: " + e.event );

    if(e.event == "registered"){
        if(e.regid.length > 0){
            log("REGISTRATION ID:  <br>" + e.regid);
            log("<a href=\"mailto:?subject=ADM%20Registration%20ID&body=" + encodeURIComponent(e.regid) + "\">Email Registration ID</a>");
        }
    } else if(e.event == "message"){
        if ( e.foreground ) {
            log("FOREGROUND NOTIFICATION");
        } else {
            if ( e.coldstart )  {
                log("COLDSTART NOTIFICATION");
            } else {
                log("BACKGROUND NOTIFICATION");
            }
        }
        log("MESSAGE: " + e.payload.message );
        log("TIME: " + e.payload.timeStamp );
        log("URL: " + e.payload.url );
    } else if(e.event == "error"){
        log("ERROR: " + e.msg );
    }
}

function handleSuccess(result) {
    log("Plugin Success: " + result );
}

function handleError(error) {
    log("Plugin Error: " + error );
}

function log(msg){
    container.innerHTML += msg + "<br>";
    console.log(msg);
}

// Client ID and Client Secret received from ADM portal
var CLIENT_ID = ""; 
var CLIENT_SECRET = "";

// Registration ID, received on device after it registers with ADM server
var REGISTRATION_IDS = [""];

// Message payload to be sent to client
var payload = {
        data: {
            message: "PushPlugin works!!",
            url: "http://www.amazon.com",
            timeStamp: new Date().toISOString()
        },
        consolidationKey: "my app",
        expiresAfter: 3600
};
...

node pushADM.js