Making Sense of Cordova Push Notification Options and APIs

The ways in which you can implement push notifications for Cordova apps can be confusing and a bit murky. This is because a) push notification architectures are somewhat complex, having both client and backend parts, and b) there’s more platform native stuff to worry about than for most Cordova client apps. The article that I published in MSDN Magazine only covered a small, simpler scenario with just Android. As such, I wanted to detail everything I know about the available options for implementing push notifications in a Cordova app in this blog post, including the following:

• Importance of the backend service (and why Azure is so worth trying).
• Client libraries and plugins for push notification in Cordova apps.
• Service-side APIs you can use for sending notifications.
• Configuring a push notification topology (mostly using Azure).

Note that this post is point-in-time picture, and hopefully push notification support for Cordova apps (particularly the client plugins) will improve in the future.

The Basic Push Notification Architecture

While discussing push notifications options, libraries, etc., it’s important to keep in mind the basic architecture and process flow of a push notification topology. For this, we’ll turn to my favorite image courtesy of the Azure Notification Hubs docs:

When deciding what plugins and libraries to use, the important considerations are what backend service are you going to use and which client platforms you want to support in your Cordova app. Just as a reminder, these are the four primary platform-specific push notification services (PNS):

• Apple Push Notification Service (APNS) – supports iOS devices.
• Google Cloud Messaging (GCM) – supports Android (but not Amazon Kindle) devices.
• Windows Notification Service (WNS) – supports Windows Store, universal Windows, and Windows Phone Store (>8.1) devices.
• Microsoft Push Notification Service (MPNS) – supports Windows Phone 7 & 8 (“Silverlight”) devices, and will not be supported going forward.

Choosing a Backend Service

The specific Cordova plugin and libraries that you will end up using will likely depend on the backend service that you choose, especially when the backend has built-in support for push notifications. This backend service must do the work of tracking the handles (tokens/channels) distributed by the PNS to a given device and sending notifications to a given device by using that handle. You can prop your own service to do this work, but then you do have to know how to talk to the major push services for Apple, Google, Microsoft, Amazon, etc.

While you could use any backend service to send push notifications to your Cordova app, there’s a huge benefit to creating an Azure backend service or publishing your service to Azure—namely Azure Notification Hubs ( I discuss this in my MSDN Magazine article). This Azure service, which you can not only use with Azure Mobile Services but with any Azure published service or on-premises service, is designed to work with all major PNS services. Notification Hubs does the “heavy lifting” of managing device handle registrations and makes it easy to send notification from various backend platforms, such as: ASP.NET (C#), Azure Mobile Services, PHP, and Node.js. You simply have to configure each PNS with the notification hub.

Because Mobile Services prides itself on being a more turnkey service for mobile apps, it also exposes registration APIs for push notifications, which are passed to the associated notification hub. You can access these registration APIs by using any Mobile Services client SDK, including the Cordova plugin.

Client-side Libraries for Cordova Push Notifications

There are four main Cordova client options that I have come across for registering a device with the PNS¹, registering the handle with the backend service,² and handling incoming notifications⁴ (note that these superscripts refer to specific steps from the above graphic). Most of these libraries are designed to work with a push topology that includes Azure Notification Hubs.

PushPlugin

This is the original push notification plugin for Cordova, which does the basic work of requesting handles¹ and handling incoming notifications⁴. Use this plugin if you have created your own custom backend solution or when registering with Notification Hubs through Mobile Services.

• Supports: APNS, GCM, WNS, MPNS
• Pros: Supports all major platforms.
• Cons: Doesn’t talk to any backend services. Requires platform-specific client code. You need to perform your own local storage of the handle.

Notification Hubs plugin

This plugin was developed by MS Open Tech folks and it does the work of PushPlugin^1,4 in a much more platform agnostic way, and it stores the registration info locally. Plus, it also registers the device and handle with Azure Notification Hubs². This is a good option for using Notification Hubs without a Mobile services backend.

• Supports: APNS, GCM, WNS, MPNS
• Pros: Supports all major platforms. Single plugin integrates getting handles/tokens and registering (native) with Notification Hubs. Client code is platform agnostic (which is what you want from Cordova, right?).
• Cons: Doesn’t support template registrations (which is a huge bummer for Cordova). Not yet in an official Azure project repo. Not integrated with the Mobile Services plugin.

Mobile Services plugin

The official Cordova plugin for Mobile Services supports registering with Notification Hubs², but only for ANPS and GCM. It also stores the handles locally, but you still need to use PushPlugin.^{1, 4} This is the scenario that I highlighted in my MSDN Magazine article.

• Supports: Only APNS and GCM
• Pros: Integrates with Mobile Services client to enable Notification Hubs registration². Officially supported in the Azure team repo.
• Cons: Only supports APNS and GCM. Still requires PushPlugin.^{1, 4}

Note that Azure App Service Mobile Apps (currently in preview) doesn’t currently have Cordova support available, but I am told the plugin will support APNS, GCM, and WNS.

Mobiles Services Push Sample

This was my first attempt at using push notifications with Mobile Services in a Cordova app, which I wrote back before the Mobile Services plugin existed. This sample includes my own push registration library that accesses the Mobile Services registration REST APIs for Notification Hubs (which IMHO are better than the Notification Hubs REST APIs)² and stores the returned handle locally . Like the Mobile Services plugin, this sample also uses PushPlugin,^{1, 4} however it does also support MPNS. It’s pretty easy to extend to other platforms supported by PushPlugin—I know folks have also added WNS support (sadly, I don’t get much time to support this sample).

• Supports: APNS, GCM, MPNS
• Pros: Leverages the Mobile Services client to enable Notification Hubs registration (3). Easy to extend to WNS.
• Cons: Doesn’t (yet) support WNS. Still requires PushPlugin.^{1, 4} Sample project is maintained only by me, and it’s not really a plugin.

Server APIs for Sending Notifications

Assuming that you are using Azure Notification Hubs to send push notifications to your Cordova app from your backend service,³ these are the Azure Notification Hubs libraries that you need to use:

For backend servers not supported by these APIs (like for PHP/Python/Ruby), you can always just use the Notification Hubs REST APIs.

Configuring the Push Topology

For each supported client platform, you must have your app configured to access the PNS.¹ You also need your backend service configured with the PNS to be able to request push notifications on behalf of your app using the PNS-generated handle.³

Client configuration

These client configuration steps are usually done in the client project must vary in complexity, depending on the PNS (and Apple is by far the hardest):

• APNS:
  1. Build the iOS native app project from the Cordova app.
  2. Open the Xcode project in Xcode on your Mac.
  3. Register an App ID for your app.
  4. Enable push notifications for the app.
  5. Verify that the app ID enables push notifications.
  6. Refresh the provisioning profiles in the Xcode quickstart project.
  7. Verify that the provisioning profile was either created or regenerated to enable push notifications

  NOTE: Most of these client configuration steps for APNS must be done in the Xcode project generated by the Cordova build for iOS. You also need an Apple Developer account to register for push notifications and a physical device to test them.

• GCM:
  1. Enable Google Cloud Messaging.
  2. Set the Google Project ID in the client (PushPlugin only).
  3. Create a new server key (make note of the API key value, which is the GCM credentials).
  4. (Optional) Setup the Android emulator for testing.

  Android is the only app that doesn’t require you to build the native app and register using the platform IDE.

• WNS:
  1. Build the Windows native app project from the VS Cordova project.
  2. Open the generated Windows project in Visual Studio.
  3. Register your app with the Windows Store.
  4. Go to the Microsoft Account developer center, select your new app, and make a note of your package SID and client secret, which are the WNS credentials.

  NOTE: You need a Windows Developer account to register for push notifications.

• MPNS:

  For folks still trying to support Windows Phone 8 and Windows Phone 8.1 "Silverlight" apps, the good news MPNS doesn't require authentication, as long as you send less than 500 notification a day (per channel).

Backend Configuration

When using Azure Notification Hubs, the final step for each platform is to set the authentication credentials from each PNS in the Azure portal. Note that when you set the push credentials in Mobile Services, they are simply passed-back to the associated notification hub.

Conclusion

Push notifications is a key requirement for many mobile app scenarios, and the PushPlugin does provide push notification support for Cordova apps. While Azure is a great platform for sending push notifications, either through Azure Mobile Services or directly from Azure Notification Hubs, the Cordova client support in Azure libraries for push notification is not quite as robust as it could be, especially if you are trying to support Windows apps when using template notifications. In the meantime, you can fall back on PushPlugin and the Notification Hubs REST APIs to support these scenarios.

Anyway, I hope that helps to clarify things, at least a little bit.

Cheers!

Glenn Gailey