azurecoder's blog

Perhaps the most useful feature of Windows Azure Mobile Services (WAMS) is notifications. I recently spoke to a small group of people at a virtual conference for Six Steps of Azure. It was all very interesting taking the polls of people there and getting their feedback on the subject matter. Firstly, I explained that notifications put the mobile into mobile services. My audience picked up very quickly that WAMS was all about the data pipeline so any REST request would kick off processes which generated comms back to the device. Notifications are really why this is so useful for a device.

We’re currently working on a project which will send out notifications from a cloud service. It’s not ideal because much of the wiring you have to put in place yourself. WAMS is different. Notifications are an intrinsic part of the platform such that you can simply send these notifications with a couple of lines of code. I’ve taken this image from a Microsoft tutorial to illustrate the flow of notifications from a Cloud Service.

The notifications workflow is described below in terms of WNS (Windows Notification Service) although WAMS now supports the Apple Notification Service. You can send notifications to Windows Phone 8 by using Microsoft Push Notification Service (MPNS) or Windows Store apps using WNS. We’ll focus on the Windows Store app given that code that this series relates to is Windows Store Code.

To register your Windows Store application for WNS go https://appdev.microsoft.com/StorePortals/en-us/Home/Index?wa=wsignin1.0.

Credentials for WNS are stored in the Mobile Services portal under the Push tab. Behind the scenes WAMS will send your “client secret” and “package sid” to WNS via the OAuth 2.0 protocol which will allow the application to authenticate and then send push notification requests continually.

The flow of how the WAMS application send a notification to the Windows Store application is fairly easy to understand.

• The client application talks to WNS and request a Channel URI
• The Channel URI is sent to WAMS
• WAMS records the URI for the device in a Channels table
• When a CRUD operation occurs the Channel URI is used to send the notification

To take advantage of receiving notifications in your Windows Store application you must associate your application with the Windows Store. As we set this up earlier we simply right-click on the context menu for our Windows Store application project and select store -> associate with Window Store. This will bring up the following dialog which will allow you to select the pre-registered application. When this process is complete it will import some signed meta-information including an XML file called Package.StoreAssociation.xml add some stuff to the application manifest and add a couple of certificates. When this process is complete the application will be primed for notifications.

The SetChannel method creates a push notification channel on the on the Windows 8 device by calling PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync. In the background this registers a new channel with WNS. In order to index this channel we need to be able to get a package specific token which can be done using this HardwareIdentification.GetPackageSpecificToken(null). This ensures uniqueness with the specific package (windows store app) on the specific device. We can then wrap this up in JSON and add this to the Channels table in WAMS (which we’ll have to create).

The insert method is then used as above in WAMS. I’ve borrowed some of this from Josh Twist’s blog and altered a couple of items. Firstly we need to ensure that we don’t put the same Channel URI into the table twice otherwise we’ll get two notifications. In order to do this we ensure that we build an effective composite key on InstallationId and UserId. Whilst still not strictly correct because you may be able to log into an application using multiple iDPs it’s a good way of avoiding duplicating channels. One important feature we need to be aware of here is that Channels can get stale so we may not be able to deliver a message to avoid this we always want to check for an updated channel when we first login to the Windows Store application. If the channel is different from channel stored in the table then we’ll update the Channel URI assuming that the previous one is out of date. Believe it or not this workflow is explicitly what you’ll need for all of your WAMS applications. Hopefully the WAMS team has picked up on this and will ensure that the glue as written here is an integral part of the next versions.

The query above use the sql driver for node.js to return all of the channels associated with a particular user since the application wants to send notifications to all registered user devices.

The following code is the only code that we need to send the notifications. You can see that the push.wns package is used to send messages to a particular channel. The GetChannels method will return all of the user Channel URIs and then iterate through them and send a notification to each one. One of the great things here is the ability to send such a wide variety of notifications. We can send toasts, tiles, badges or raw notifications to a mobile or Windows Store client. 

The notification method names are fairly intuitive. sendToastImageAndText04 will send a test to the application and display and image and some text. sendToastText04 will just display a toast with a small amount of text on. The other two are based on sending updates to the Tile (Live Tiles!). sendTileWideImageAndText01 and sendTileSquarePeekImageAndText01 are two of several ways of updating tiles and badges. The latter is pretty savvy is it allows a photo, a piece of text and 4 pieces of scrolling text on the live tile all transitioning between each state.

So notifications are as simple as that!

We’re not finished yet though. It’s important to be able to integrate alerts to devices that may not be able to receive notifications but can receive SMS messages. As such I’ll describe how you can send SMS and email from your service.

If you haven’t already signed up for Twilio do it! Twilio is a fantastic service which gives you the ability to send automated callbacks and text messages from your Mobile Services applications. You can sign up at twilio.com. The process takes seconds, you register with them and they give you 1000 free text messages. The text can be sent to mobile services to all of the initial mobile numbers you register and authorise.

The code from the sample below is an effective web form post in code. It uses the node request package to construct a request (HTTP POST) and send this to Twilio. By now you should be able to see that OAuth permeates everything we do and the id and secret is present in this form post in the form of an account_sid and auth_token. The From and To are the phone number that Twilio gives you on sign up (0203 if you’re in the UK) and any mobile number you’ve registered.  

Lastly (if you’re not tired yet of spamming your users with every known means of messaging!) we’ll look at SendGrid. Sendgrid is a REST/SMTP based mail service which can be used from Azure easily. The Sendgrid team has supplied a node package and it’s very easy to use.

In order to access the SendGrid service you need the username and password you registered with. Registration is easy and allows you to get up to 6000 emails a month with the caveat that it is part manual and someone has to authorise you so you’ll need to have a valid  company etc. The code above shows how easy it is to send an email. Simply require the sendgrid package, login to sendgrid, set your email parameters and send.

There you go. Have fun sending messages in different ways to devices. I hope you can see how easy Mobile Services makes this for developers.