Last week we announced that Notification Hubs had reached General Availability (GA). GA means that if you had any doubts before about the production ready-ness of the service, you can stop worrying and start using! Notification Hubs enables you to deliver broadcast push notifications to Android, iOS, Windows 8, and Windows Phone applications with ease.
Notification Hubs vs Mobile Services for Push Notifications
If you’ve been paying attention to Windows Azure over the past year, you’ll know that we also have a great service called Mobile Services. Mobile Services is a great Backend-as-a-Service offering that offers lots of great features for anyone building a mobile application (whether it’s Android, iOS, Windows, or Windows Phone). One of these features is push notifications to all of those platforms using APNS, GCM, MPNS, and WNS. The obvious question one would have knowing that Mobile Services supports push notifications and that Notifications Hubs do as well is when should I use which? Thankfully I have a pretty handy table which will help you understand things:
Mobile Services
Notification Hubs
APNS, GCM, MPNS, WNS
Yes
Yes
Turnkey event-triggered push
Yes
No
Device registration management
No
Yes
Interest tags for routing messages to a subset of users
No
Yes
Templates for formatting messages to user preferences including language
No
Yes
Broadcast to >= 1 million devices at once within minutes
No
Yes
In short, if you want to do an event-triggered push notification, Mobile Services can handle this very easily. If you want to trigger push notifications to a large group of users, Notification Hubs will handle things better. It’s entirely possible for there to be overlap (you could trigger a push to an individual device or user with Notification Hubs and you could push to many users with a Mobile Service) but in general, they each have a scenario they are better for. What’s great is that there is nothing to stop you from using both with your applications. I’m working on a sample right now that uses Mobile Services to trigger a push when one user sends a message to another but uses Notification Hubs when I want to deliver a message to all of the users (to let them know there is a new version of the app for example).
Subscribing to Notification Hubs
Subscribing to a Notification Hub is very easy work no matter which platform you’re working with (well, in the case of APNS, you do need to sort out the certificate / App ID stuff first). If you haven’t set up push notifications on whichever platform you’re working with, I would recommend taking a look at the extensive walkthrough provided for each platform here:
Because the steps required just to set up push notifications for each platform don’t really have to do with Notification Hubs, I would look at those tutorials if you aren’t familiar with how to get an API Key for GCM, a push cert for APNS, or a client secret and package SID for WNS. Provided you already know how to deal with those steps, I’ll detail the actual code involved with subscribing to a hub.
Subscribing from Android
After you’ve created a Notification Hub in the Windows Azure portal and put your API key into it’s configuration settings, the next step is to do the work on your client side. First, make sure you’ve installed the Google Cloud Messaging for Android Library and Google Play services using the Android SDK Manager. This library shows up under the Extras folder as opposed to under a specific API level. Once that is installed, copy the gcm.jar file from /your-android-sdk-directory/extras/google/gcm/gcm-client/dist/ and place it in your project’s libs folder. You’ll then need to copy google-play-service.jar from /android-sdk-directory/extras/google/googleplayservices/libproject/google-play-services_lib/libs into your libs folder. Also, remember that when testing this, your emulator (or device) must be running with Google APIs. Otherwise it can’t work with GCM. The last library we will need is the Notification Hubs Android SDK which you can download from here. After downloading, open the zip and copy the notification-hubs-sdk.jar over to your libs directory.
Once that is done, open your project’s AndroidManifest.xml file. You’ll need to add the following inside of the manifest element:
Make sure you replace the <your package> with the name of your app’s package (just look up in the manifest attributes to find it). With that done, hop over to whatever activity runs when your app launches. This is where we are going to start the registration process for Push Notifications. Add the following private variables to your activity class:
Make sure you replace the <Project ID from Google API Console> with your project ID. You can get this by going to the Google API Console and selecting your project from the drop down in the top left. Your project will then be in the URL (in the address bar) next to project:. Next go to your activity’s onCreate method and add the following:
Here you’ll need to enter the name of the notification hub where you see <Notification Hub Name> and the DefaultListenSharedAccessSignature where you see <Notification Hub Listen Access Connection String>. You can get this connection string by going into the Windows Azure portal and going into your Notification Hub (your Notification Hub will be under the Service Bus area on the left side of the portal). Then click on the Dashboard link for your hub. At the bottom of the next screen will be a button with a key that says Connection Information. Click that and you’ll see the two connection strings you’ll need (the one you need now is the Listen signature, later we’ll use the Full one):
After you’ve copied and replaced those values, you can then add the registerWithNotificationHubs method:
This method will start up a background task that will first register with GCM. When GCM get’s back to our application with a RegistrationId (which is how GCM identifies our device and app) we can then send it up to our hub by calling hub.register(regid). The last step we need to handle on the client side is specify what should handle the notifications sent to our app. To handle this, let’s first go to the Manifest file and drop this xml in beneath the Activity but in the Application element:
Again, make sure you replace the <Package Name> with the package of your app. This xml basically tells Android that when we receive a push notification, the MyBroadcastReceiver method should handle it. Now add a new class to your source code named MyBroadcastReceiver. Make it’s superclass android.content.BroadcastReceiver. Now we implement it’s onReceive method to handle displaying a notification to the user:
Here, depending on what is received, we call the sendNotification method with a specific message. The sendNotification method then handles displaying a toast notification to the user. Now we’re ready to register for and receive push notifications from our hub. Before we talk about how to deliver them. Let’s take a quick look at registering with your hub on iOS.
Subscribing from iOS
Setting up push notifications for iOS is both easier and harder than Android. Within our app, there is less code we need to do. However, the steps involved in creating an App ID, a push certificate, a provisioning profile, etc are fairly complex. If you haven’t done it before, I highly recommend going through the full documentation found here. Once you’ve done that, start by downloading the Mobile Services iOS SDK here. This zip contains both the Mobile Services SDK (which we don’t need to use for Notification Hubs) and the WindowsAzureMessaging.framework. Copy that framework into your app’s Frameworks folder. After that, open up your AppDelegate.m. We’ll start by adding the following import statement near the top of the file:
#import <WindowsAzureMessaging/WindowsAzureMessaging.h>
Now, add the following code into the didFinishLaunchingWithOptions method:
This will trigger our app to talk to APNS and request a token for push notifications. Now we’ll add a new method which will handle the call back when APNS responds to our app:
Here you’re going to need to replace <Connection String> with the Listen signature I mentioned earlier on. You’ll also need to put your hub’s name into <Notification Hub Name>. This will take the token, which identifies our app and device to APNS, and sends it up to our hub. Finally we need to put another method into our AppDelegate which will handle displaying the notification if our app is in the foreground when it’s received (if our app is in the background, iOS decides how it’s going to display it):
Here we’re just going to log whatever information was received and then present it using a UIAlertView. You’ll need to make sure the correct provisioning profile is also selected in your app’s Build Settings but refer to the earlier link if you’re not sure how to do that.
Triggering Push Notifications
You’ve got a few different options for actually triggering push notifications down to your applications. First, there is a REST interface exposed by Notification Hubs. This effectively means that anything capable of doing an HTTP Request could be used to trigger a push. There is also a WindowsAzure.ServiceBus NuGet package which can be used to trigger a push from just about any form of .NET Client (console app, website, etc). We won’t be looking at either of these two options today but you can research them more if you’d like to see how they work. Instead, today we’ll be using Mobile Services to trigger our push notifications. Specifically, we’re going to trigger the push with a scheduled script in our Mobile Service. If you’re not familiar with Mobile Services or scheduled scripts, take a look at this post I put up a while back. For today, we’ll create a Scheduler script named testNotificationHub and we’ll define that script as so:
First we require the azure module. This is what gives us access to Service Bus and Notification Hubs. We then use that module to create a Notification Hub Service accessor. Make sure you replace the <Notification Hub Name> and <Full Signature Connection String> parameters. This is when you want to use the second signature from your hub and not the Listen one. We then make two calls: one to push to GCM and one to push to APNS. I’m doing that like this here because they both expect different payloads. If all of our configuration went correctly, we should see a new notification in the Notification Manager in Android and either a toast in iOS (if our app is backgrounded) or a UIAlertView if our app is running in the foreground.
Tags and Templates
One thing I’m not covering in any detail today is the ability to register with tags as well as the ability to push using templates. With tags, you’re able to say “this device / app is interested in tag X”. Then on your server side, you can, when desired, trigger pushes to any apps that have registered with that tag. An easy to understand scenario is sport teams. Let’s say I’m building an application which delivers news about sports teams to it’s users. Well if I get some news on the Detroit Tigers and want to inform all of the users that care about the Tigers, I could do it with tags. On the client side, I would just need some way for a user to say “I’m interested in the Tigers” then I would make another call to my hub and say “This app wants Tigers news”. Then on the server I would just push to the “Tigers” tag.
Templates allow you to define how a push should be delivered given what platform it’s being sent to. In the above example, I made a different call for APNS and GCM because they expected different payloads. With templates, you can say “if I’m delivering to APNS, send this payload in this format but if I’m sending to GCM, deliver it in this format”. This allows you to make a single call to hub.send(…) where you specify some information that then gets put into those templates. You can read more about using templates here.
Videos
In addition to this post and all of the content on the Windows Azure dev center. Both myself and Elio Damaggio (one of the Program Managers on Notification Hubs) have recorded videos showing Notification Hubs in action. My video focuses on connecting iOS to Notification Hubs and using Mobile Services to trigger pushes and can be watched here. Elio’s video focuses more on the Windows Store side of using Notification Hubs and can be watched here.
Summary
With Notification Hubs, developers have a great way to combine targeted push notifications with push notifications on a massive scale. Just think of millions of push notifications going out to all the different device platforms without you having to worry about how it works, or making sure it will work. We’re going to continue to enhance the functionality and capabilities of Notification Hubs and would love your ideas. If there is a feature of Notification Hubs you’d like to see, please suggest it on the My Great Windows Azure Idea for Notification Hubs. If you start using Notification Hubs, I’d love to hear about it!
