Chris Risner . Com

Android, Push Notifications, and Azure

Posted on: 9/5/2014 4:35:00 PM by

A while back (a year ago counts as awhile back, right?), I posted about the General Availability of Azure Notification Hubs.  Since then, I’ve given a few presentations at different conferences (TechEd, AnDevCon, CocoaConf, 360iDev, etc) on how you can make use of Notification Hubs to power your push notifications.  However, I haven’t really posted about it or released sample code demonstrating how it works on the different platforms.  Technically, I did release a very comprehensive app, named LensRocket, that uses Notification Hubs, however, that is a huge sample so if you’re just looking for “how do i do push?” it might be confusing.  Today I’m going to start fixing that by releasing a fairly comprehensive explanation of push focusing on Android clients.  I actually just posted the same walkthrough for iOS a few days ago.  For clarity sake, and so you don’t have to hop between the two posts, I’m going to reexplain all of the things which both Android and iOS have in common here.  Note that if you want to pull down the completed app, you can access all of the source code here in GitHub.

Push Notifications

For those who may not already know, I’ll give a quick overview of what Azure Notification Hubs are and why they exist.  When building client applications (whether they’re iPhone, Android, WinPhone, or WinStore apps) one of the capabilities apps have is to receive Push Notifications.  Push Notifications are a way of delivering information to your app without your app having to go out and request it.  These pushes could inform the user / app of many many different things and just a few examples of them include: you’ve received an email (including increasing a badge number), play a sound, display a message, download some data from a server.  What’s really key here is that you can send this information down to a device without your app needing to request it first, or without your app even running!  This means that push notifications end up being used a LOT.  Fortunately, when you’re building an app (regardless of the platform) it’s pretty simple for you to take advantage of push notifications. 

For each client platform, there is a Push Notification Service (PNS) provided by the vendor primarily responsible for the OS.  So:

  • iOS has Apple Push Notification Service (APNS)
  • Android has Google Cloud Messaging (GCM) and Amazon Device Messaging (ADM) for Google Android and Amazon Android, respectively
  • WinPhone has Microsoft Push Notification Service (MPNS)
  • Windows Store has Windows Notification Service (WNS)
  • Other OSes provide their own services but are more bit players

Each of these PNS will provide to your application some identifier that identifies your app and device to the PNS.  Once you get this identifier, you can then use it to talk to the PNS and ask it to deliver a push notification to the device / app.  While you COULD request a push from the same device that you’re running the app on, what is common practice is to have a backend somewhere that you send the identifier to.  This backend can then talk to the PNS and request a push.  This backend could be a website running somewhere, a web service, a virtual machine, a client application, or really anything else capable of making an HTTP request to the PNS. 

Notification Hubs

So far we have a client app, we have a PNS, and we have a backend.  Let’s talk about how Notification Hubs fits into this.  Notification Hubs is basically built to be a pseudo backend / service that will handle talking with the PNSes.  That’s a pretty big simplification though because there is a lot behind that.  First, when your backend asks a PNS to deliver a push notification, every request has to be signed with either an API key or a certificate (depending on which PNS it is).  So not only does NH need to be able to handle taking in the keys / certs and using them for each request, it needs to be capable of updating to new versions as the certs do expire!  While that’s more of administrative details, NH also enables easy targeting of push notifications using Tags (more on this below) as well as enabling single line of code cross-platform push via templates (more on this also below).  Let’s start seeing some code so we understand how this works.

Setting up GCM and Starting on the Client

Today we’re going to be focusing on using GCM to push to Google Android devices.  On the client side, setting up your app for push notifications is probably more complicated for Android than any of the other platforms.  The first step you need to follow is to go to the Google API Console and generate a new project, enable the Google Cloud Messaging API, and then create a Public API Access key.  You can follow along with step by step instructions for doing so here.  Once you’ve done that, you’re ready to proceed with client changes.  Before we edit any files, we need to put the Notification Hubs jar into our libs folder.  You can download the libraries from here.  Make sure to copy over the notification-hubs-X.jar and the notifications-X.jar into your libs folder and then refresh that folder in your IDE.

Next, open the AndroidManifest.xml file in your Android project.  We first need to add the necessary permissions inside the manifest element:

Make sure you replace the PACKAGE in the bottom two lines with the package of your actual application.  The last step in our manifest is to specify the receiver:

Again here we need to replace PACKAGE with the package of the application.  The com.microsoft.windowsazure.notifications.NotificationsBroadcastReceiver is a helper we get from the Notification Hubs library.  Up next we’ll set up our Notification Hub on the server side before we switch back to the client.

Setting up Notification Hubs and your Project

Head over to the Azure Portal and create a new Notification Hub.  If you haven’t done that before, it’s documented here.  Once you’re done with that, go to your Hub in the portal and go to the CONFIGURE tab.  Find the area for google cloud messaging settings.  Copy the server API Key you got from the Google API Console into this and save the changes.  Next, go to the DASHBOARD tab for your service and click on the CONNECTION INFORMATION button at the bottom.  You’ll want to copy the Listen and Full Shared Access Signature’s for later.  Now we can head back to the client.

Registering with GCM

We’ll do two things now.  First we’ll handle getting an instance of a GoogleCloudMessaging object and then we’ll set up our Notification Hub for later:

In the demo app, this code is in my fragment’s onCreateView method but you may want it elsewhere.  You’ll need to replace the NotificationHubName and NotificationHubListenSharedAccessSignature with the values from your Notification Hub (that you just got a second ago).  Next we’ll add a method that will go out to GCM and register.  In the demo app, I’m triggering this from a button tap, but you might want to do it right after you create the GCM object above:

Here we’re starting a background async task (to not block the main thread) and telling it to go and register with GCM.  We’re passing in a SENDER_ID which should be the Project Number of your project in the Google API Console (note that this is the Project Number and NOT the Project ID).  The last thing we need to do before moving on to talking with our Hub is create something to handle receiving push notifications.

The NotificationsHandler

If you’re adding the code to your own project (as opposed to using the referenced demo code), you’ll want to add a new class to your project named MyHandler which inherits from NotificationsHandler.  Here’s the code for our class:

The NotificationsHandler base already handles a few things for us .  All we need to do is override the onReceive method and dictate what we want to happen when we receive a notification.  Here we’re calling into a sendNotification method which will first use the NotificiationManager to display a notification in the status bar at the top of the device.  Then it will also display a toast on the screen of the app.  Now that we’re able to display our notifications when we receive them, we’re ready to start registering with our hub and then sending out push notifications.

Broadcast Push

Broadcast push is a way of doing untargeted push notifications.  In other words, push to all of the Androiddevices that have registered with my hub.  Let’s look at the client side code first:

Here we’re calling register on the hub we created earlier and we’re just passing in the registration ID we received from GCM.  When this runs it will contact our hub and basically say “I’m an Android device that is registered with GCM, here’s my registration ID.”  Now let’s look at the server side code to trigger a push.

Here you’ll replace the strings in call to createNotificationHubService with your hub’s name and the FULL Access Signature.  We then use the notificationHubService object to call gcm.send where we specify the payload we want to send.  Running this script will trigger our hub to push that payload to any Android / GCM device that has connected to the hub.  One other thing to note is that these scripts were created to be run as Mobile Service Custom APIs in order to ease testing out (with the permissions set to Everyone, I can trigger this script by going to the endpoint for it in a browser).  I’ll talk more about connecting to Notification Hubs to trigger pushes later, but for now just know that this same Node.JS Script could run anywhere you can run Node.  You’d just need to pull down the Azure Node Package.

Pushing to Tags

Up next we’ll talk about targeted pushes.  So instead of “Broadcast to everyone” we’ll be able to say “Push to user X” or “Push to this group of users”.  The first step in doing this is registering from the client:

This is identical to the code we had on our client before except now we’re passing in additional parameters which are tags.  In this case, my array has three tags: MyTag, AllUsers, and AndroidUser.  When we run this it basically says, “I’m an Android device that is registered with GCM, here’s my push token.  Also, tie it to these three tags.”  What’s great about this is then from our backend, we can tell our hub to only push to devices that are tied to a specific tag, like this:

Here we’re doing the same thing on the server, EXCEPT we’re passing in a first parameter (previously it was null).  In this case we’re passing in the tag MyTag so only devices registered with my hub, with GCM, will receive the push notification.

Tag Expressions

Pushing based off of tags is pretty cool.  You could use tags for lots of different things (sports teams, stock ticker labels, zipcode (i.e. geopush), etc).  You could even set the user’s username (if they were logged in) as a tag and then you’d have the ability to say “push to all of Chris’ devices” if you wanted.  Another powerful feature of hubs is called Tag Expressions.  This basically enables you to trigger pushes based off logical expressions of tags.  So for example, if I was registering with the username and a group I’m in, I could say “Push to GROUPNAME except ME”.  So push to everyone in the group I’m in but not my devices.  The actual tag string I would use would probably look something like this “Group:ID && !User:ID” where the tags I register with might be “Group:ID” and “User:ID”.

Templates

So far we’ve looked at broadcast and targeted based push.  However, all of the pushing we’ve done has been constrained to GCM devices.  If I’m building a cross-platform app, I need to be able to handle pushing to other platforms as well.  Now I could have the same code to do a push to iOS and WinPhone and WinStore right after my gcm.send code everywhere I want to do a push, but that’s a decent amount of code.  Especially if I am pushing in many different places.  The alternative to that is using Templates.  When you register with your hub, in addition to sending the push identifier and the tags you want to be tied to, you can also specify a template that indicates the format of the payload you want to receive.  Let’s take a look:

Here we’re creating a template string that contains the data JSON format that we previously saw in our server script.  Inside of that payload is the important bit $(message).  From the server side, when we push, it will use that message bit to figure out how to format the payload with the data we want to inject.  The other difference here is that we’re now calling registerTemplateWithDeviceToken.  Let’s take a look at the Node script to push to our client now:

Now we’re creating a payload object which is a JSON object with a message field in it.  We can then use notificationHubService.send (notice there is no gcm in the middle anymore) and set the payload as the second parameter (we’re not using a tag to do a targeted push here but we could).  When this runs, it will cause the hub to find any device registration that has a payload with the message field in it and format the payload with the data from the payload we’re sending in.  So effectively, when we send to our Android device, we’ll use the gcm payload format specified on the client.  If i was doing something for iOS, we’d send it in the iOS specific format, and so on.  So we now have a single line that is capable of handling pushing to any device type!

Talking to Notification Hubs from Your Backend

The idea here is that Notification Hubs can effectively handle all the aspects of Push Notifications for you.  I can have a backend (website or web service) running somewhere, whether its on Azure or not or it’s in .NET or not doesn’t matter at all, and just talk to my Notification Hub whenever I need to trigger a push.  Now in the samples above, I’m trigger my pushes from Node.js scripts which make use of the Node.js Azure module.  These could be running anywhere but to make things easy, I usually run them from Azure Mobile Services (super quick to get them up and running).  You can also use the .NET SDK for triggering push notifications, and their are guides for doing so from Java as well as from PHP.  Everything in Notification Hubs is also exposed over a REST API so even if there isn’t an SDK or a guide for talking to your hub from your platform of choice to trigger pushes, you can always fall back on the REST API.

Summary

I hope this post proves helpful for anyone looking at using Notification Hubs to handle Android push notifications.  If you also look at the iOS walkthrough, you’ll see that the majority of the code is either the same or very similar.  Notification Hubs are a super easy way to get into doing push notifications for your apps and make it super simple to make them working on different platforms.  Add to all these features the fact that you get 1 million push notifications for FREE every month (as of Sept. 1, 2014) and it’s a pretty sweet deal!  You can grab both the client and server source code for the app seen above here.

Categories: Android, Azure, Java, Javascript
Bookmark and Share
First Article

iOS, Push Notifications, and Azure

Posted on: 9/2/2014 9:42:00 PM by

A while back (a year ago counts as awhile back, right?), I posted about the General Availability of Azure Notification Hubs.  Since then, I’ve given a few presentations at different conferences (TechEd, AnDevCon, CocoaConf, 360iDev, etc) on how you can make use of Notification Hubs to power your push notifications.  However, I haven’t really posted about it or released sample code demonstrating how it works on the different platforms.  Technically, I did release a very comprehensive app, named LensRocket, that uses Notification Hubs, however, that is a huge sample so if you’re just looking for “how do i do push?” it might be confusing.  Today I’m going to start fixing that by releasing a fairly comprehensive explanation of push focusing on iOS clients.  I’ll follow this up shortly with the same walkthrough for Android.  Note that if you want to pull down the completed app, you can access all of the source code here in GitHub.

Push Notifications

For those who may not already know, I’ll give a quick overview of what Azure Notification Hubs are and why they exist.  When building client applications (whether they’re iPhone, Android, WinPhone, or WinStore apps) one of the capabilities apps have is to receive Push Notifications.  Push Notifications are a way of delivering information to your app without your app having to go out and request it.  These pushes could inform the user / app of many many different things and just a few examples of them include: you’ve received an email (including increasing a badge number), play a sound, display a message, download some data from a server.  What’s really key here is that you can send this information down to a device without your app needing to request it first, or without your app even running!  This means that push notifications end up being used a LOT.  Fortunately, when you’re building an app (regardless of the platform) it’s pretty simple for you to take advantage of push notifications. 

For each client platform, there is a Push Notification Service (PNS) provided by the vendor primarily responsible for the OS.  So:

  • iOS has Apple Push Notification Service (APNS)
  • Android has Google Cloud Messaging (GCM) and Amazon Device Messaging (ADM) for Google Android and Amazon Android, respectively
  • WinPhone has Microsoft Push Notification Service (MPNS)
  • Windows Store has Windows Notification Service (WNS)
  • Other OSes provide their own services but are more bit players

Each of these PNS will provide to your application some identifier that identifies your app and device to the PNS.  Once you get this identifier, you can then use it to talk to the PNS and ask it to deliver a push notification to the device / app.  While you COULD request a push from the same device that you’re running the app on, what is common practice is to have a backend somewhere that you send the identifier to.  This backend can then talk to the PNS and request a push.  This backend could be a website running somewhere, a web service, a virtual machine, a client application, or really anything else capable of making an HTTP request to the PNS. 

Notification Hubs

So far we have a client app, we have a PNS, and we have a backend.  Let’s talk about how Notification Hubs fits into this.  Notification Hubs is basically built to be a pseudo backend / service that will handle talking with the PNSes.  That’s a pretty big simplification though because there is a lot behind that.  First, when your backend asks a PNS to deliver a push notification, every request has to be signed with either an API key or a certificate (depending on which PNS it is).  So not only does NH need to be able to handle taking in the keys / certs and using them for each request, it needs to be capable of updating to new versions as the certs do expire!  While that’s more of administrative details, NH also enables easy targeting of push notifications using Tags (more on this below) as well as enabling single line of code cross-platform push via templates (more on this also below).  Let’s start seeing some code so we understand how this works.

Registering with APNS

The code to register with APNS is all standard Objective-C and doesn’t have anything to do with NH:

Here we have two methods in the AppDelegate.  The first didFinishLaunchingWithOptions is the first point in the app’s code that you can start doing things.  Here we call registerForRemoteNotificationTypes and pass in the types of push we might want to receive.  The second method, didRegisterForRemoteNotificationsWithDeviceTokenb is the callback that is invoked when APNS responds.  Here we’re just saving that as a property on the view controller.  The last method above is the didReceiveRemoteNotification method which is called when our app is in the foreground and receives a push notification.  Here we could do anything we want (show something to the user, pull down more data, play a sound, etc) based off the data sent over.  In this case we’re pulling out a value and displaying a UIAlertView.

Setting up Notification Hubs and your Project

The next thing you’ll want to do is get the push certificate for your app identifier from the Apple Dev Portal and create a Notification Hub in the Azure portal.  If you haven’t done either of those before, they’re both documented in detail here.  Once you’re done with that, go to your Hub in the portal and go to the CONFIGURE tab.  Find the area for apple notification settings and upload your p12 certificate file.  Be sure to select the MODE (either production or sandbox) that corresponds to your cert type (as obtained in the Apple Dev Portal) or pushing won’t work.  After that’s done, you’ll need to download the Azure Mobile SDK.  Note that this download currently contains two frameworks: one for Mobile Services and one for Notification Hubs.  We’ll only be using the Notification Hubs framework so you can ignore the other.  Copy the WindowsAzureMessaging.framework into your project. Before you continue on, make sure the Bundle Identifier (Found in your iOS project’s General Settings) matches the one you created in the Apple Dev Portal.  Then go to your project’s Build Settings and set the Provisioning Profile and Code Signing Identity to the ones generated to match your App ID.

Creating a Notification Hub Instance

The first step in our apps code for talking to our hub is to set up a SBNotificationHub.  I’ve added a property to hold this value in my ViewController and then will instantiate it in the viewDidLoad method:

You’ll want to get the hub name from the hub you created and the ListenSharedAccessSignature can be obtained by going to the DASHBOARD tab of your hub in the portal and clicking CONNECTION INFORMATION at the bottom.  Make sure you DO NOT get the full signature for now.  Now you’re ready to start using your hub. 

Today, we’re going to go over three different ways of registering and the accompanying way to push for that registration.  The first is just plain registration with the hub which will facilitate Broadcast push (i.e. push to all the iOS devices).

Broadcast Push

Broadcast push is a way of doing untargeted push notifications.  In other words, push to all of the iOS devices that have registered with my hub.  Let’s look at the client side code first:

Here we’re calling registerNativewWithDeviceToken on the hub we just created.  Note that the first parameter is the push token we receive from APNS and the second parameter is currently nil.  When this runs it will contact our hub and basically say “I’m an iOS device that is registered with APNS, here’s my push token.”  Now let’s look at the server side code to trigger a push.

Here you’ll replace the strings in call to createNotificationHubService with your hub’s name and the FULL Access Signature.  We then use the notificationHubService object to call apns.send where we specify the payload we want to send.  Running this script will trigger our hub to push that payload to any iOS / APNS device that has connected to the hub.  One other thing to note is that these scripts were created to be run as Mobile Service Custom APIs in order to ease testing out (with the permissions set to Everyone, I can trigger this script by going to the endpoint for it in a browser).  I’ll talk more about connecting to Notification Hubs to trigger pushes later, but for now just know that this same Node.JS Script could run anywhere you can run Node.  You’d just need to pull down the Azure Node Package.

Pushing to Tags

Up next we’ll talk about targeted pushes.  So instead of “Broadcast to everyone” we’ll be able to say “Push to user X” or “Push to this group of users”.  The first step in doing this is registering from the client:

This is identical to the code we had on our client before except now we’re passing in a second parameter, an NSArray of tags.  In this case, my array has three tags: MyTag, AllUsers, and iOSUser.  When we run this it basically says, “I’m an iOS device that is registered with APNS, here’s my push token.  Also, tie it to these three tags.”  What’s great about this is then from our backend, we can tell our hub to only push to devices that are tied to a specific tag, like this:

Here we’re doing the same thing on the server, EXCEPT we’re passing in a first parameter (previously it was null).  In this case we’re passing in the tag MyTag so only devices registered with my hub, with APNS, will receive the push notification.

Tag Expressions

Pushing based off of tags is pretty cool.  You could use tags for lots of different things (sports teams, stock ticker labels, zipcode (i.e. geopush), etc).  You could even set the user’s username (if they were logged in) as a tag and then you’d have the ability to say “push to all of Chris’ devices” if you wanted.  Another powerful feature of hubs is called Tag Expressions.  This basically enables you to trigger pushes based off logical expressions of tags.  So for example, if I was registering with the username and a group I’m in, I could say “Push to GROUPNAME except ME”.  So push to everyone in the group I’m in but not my devices.  The actual tag string I would use would probably look something like this “Group:ID && !User:ID” where the tags I register with might be “Group:ID” and “User:ID”.

Templates

So far we’ve looked at broadcast and targeted based push.  However, all of the pushing we’ve done has been constrained to APNS devices.  If I’m building a cross-platform app, I need to be able to handle pushing to other platforms as well.  Now I could have the same code to do a push to Android and WinPhone and WinStore right after my apns.send code everywhere I want to do a push, but that’s a decent amount of code.  Especially if I am pushing in many different places.  The alternative to that is using Templates.  When you register with your hub, in addition to sending the push identifier and the tags you want to be tied to, you can also specify a template that indicates the format of the payload you want to receive.  Let’s take a look:

Here we’re creating a template string that contains the aps JSON format that we previously saw in our server script.  Inside of that payload is the important bit $(message).  From the server side, when we push, it will use that message bit to figure out how to format the payload with the data we want to inject.  The other difference here is that we’re now calling registerTemplateWithDeviceToken.  Let’s take a look at the Node script to push to our client now:

Now we’re creating a payload object which is a JSON object with a message field in it.  We can then use notificationHubService.send (notice there is no apns in the middle anymore) and set the payload as the second parameter (we’re not using a tag to do a targeted push here but we could).  When this runs, it will cause the hub to find any device registration that has a payload with the message field in it and format the payload with the data from the payload we’re sending in.  So effectively, when we send to our iOS device, we’ll use the aps payload format specified on the client.  If i was doing something for Android, we’d send it in the Android specific format, and so on.  So we now have a single line that is capable of handling pushing to any device type!

Talking to Notification Hubs from Your Backend

The idea here is that Notification Hubs can effectively handle all the aspects of Push Notifications for you.  I can have a backend (website or web service) running somewhere, whether its on Azure or not or it’s in .NET or not doesn’t matter at all, and just talk to my Notification Hub whenever I need to trigger a push.  Now in the samples above, I’m trigger my pushes from Node.js scripts which make use of the Node.js Azure module.  These could be running anywhere but to make things easy, I usually run them from Azure Mobile Services (super quick to get them up and running).  You can also use the .NET SDK for triggering push notifications, and their are guides for doing so from Java as well as from PHP.  Everything in Notification Hubs is also exposed over a REST API so even if there isn’t an SDK or a guide for talking to your hub from your platform of choice to trigger pushes, you can always fall back on the REST API.

Summary

I hope this post proves helpful for anyone looking at using Notification Hubs to handle iOS push notifications.  As I said above, I’ll post a tutorial on doing the same thing from Android (though it will be 90% the exact same post because only the client side code is really different) and you can do everything I’ve described above from any of the other client platforms.  Notification Hubs are a super easy way to get into doing push notifications for your apps and make it super simple to make them working on different platforms.  Add to all these features the fact that you get 1 million push notifications for FREE every month (as of Sept. 1, 2014) and it’s a pretty sweet deal!  You can grab both the client and server source code for the app seen above here.

Bookmark and Share
First Article