Mobile Services will get migrated to App Service

Universal Windows Platform support in Mobile Apps

Parse Server template in the Azure Marketplace

30 Days of Zumo.v2 blog series

Glenn Gailey

NOTE: I’m also keeping an eye on an issue that the team is working on to whitelist tags so that clients can supply a set of pre-defined safe tags during registration. When that finally gets done, I will blog about it as it should be a bit easier than this, and not require an additional round-trip to the backend to add tags.

POST https://todolist.azurewebsites.net/api/updatetags/f211a45f-6f6d-4189-b106-e534af999fff HTTP/1.1
Host: todolist.azurewebsites.net
Content-Type: application/json
ZUMO-API-VERSION: 2.0.0
Content-Length: 20

["test","broadcast"]

// Define a POST operation that updates installation tags. 
router.post('/:id', function (request, response) {
	
	// Get the notification hub used by the mobile app.
	var push = request.azureMobile.push;
	var installationId = request.params.id;

	// Get the tags array from the request message.
	var tags = request.body;

	// Validate for and block any SID tags.
	for (i = 0; i < tags.length; i++) {
		if (tags[i].search("sid:") !== -1) {
				response.status(403)
				.send("You cannot set '" + tags[i] + "' as a tag.");
				return;
		}
	}
	
	// Define an update tags operation.
	var updateOperation = [{
		"op": "add",
		"path": "/tags",
		"value": tags.toString()
	}];		
	
	// Update the installation to add the new tags.
	push.patchInstallation(installationId, updateOperation, function(error, res){
		if(error){
			logger.error('An error occurred when adding tags', error);
			response.status(error.statusCode).send(error.detail);
		}
		else{
			response.status(200).send(tags);
		}
	});		
});

// Define GET operation that returns tags for an installation. 
router.get('/:id', function (request, response) {
	// Get the notification hub used by the mobile app.
	var push = request.azureMobile.push;
	var installationId = request.params.id;
	
	push.getInstallation(installationId, function(error, installation, res){
		if (error){					
			// Log the error and send an error response.
			logger.error('An error occurred when retrieving installation', error);
			response.status(error.statusCode).send(error.detail);					
		}
		else{
			// Return an array of current tags.
			response.json(installation.tags);	
		}				
	});
});

app.use(mobileApp);    
// Add the router module on the custom API endpoint. 
app.use('/api/updatetags', require('./api/UpdateTags.js'));
app.listen(process.env.PORT || 3000);   // Listen for requests.

Glenn Gailey

Microsoft acquiring Xamarin

Hot off the presses….As ScottGu writes in his blog today, an excellent marriage is finally going to happen with Microsoft agreeing to purchase Xamarin. This is great news for .NET app developers, and something that many have long expected, wished for.

Mobile Apps Node.js backend declared GA

A great milestone for the Node.js backend version of Mobile Apps as the JavaScript-based backend reaches the “general availability” milestone. You can get it now on npm.

All of the Mobile Apps tutorials now have both .NET backend and Node.js backend examples. There is also guidance for working with the Node.js backend SDK. If you are still using Mobile Services because you loved the Node.js backend, the time to upgrade to Mobile Apps is now.

New Cordova client support for Mobile Apps

For those of you who have been waiting patiently for Cordova support in Mobile Apps, great news. A beta Cordova client plugin is now available. Even better, this is the first official Azure Cordova client that has support for WNS, so you can send push notifications to your Cordova app running on a Windows app using WNS. At this point, we have the core tutorials (focused on Android for now) and a client SDK topic.

Upload files to Mobile Apps

You obviously can’t store blob data (image/audio/video files) in the same database as regular mobile data. Mobile Apps now makes storing blobs a much more integrated and turnkey process than in the past, including support for offline sync. Check out the new tutorial for file upload, as well as the sample project.

Quickstart completed samples

Folks have been asking for years for us to publish the finished versions of the TodoList sample project featured in all of the Mobile Apps and Mobile Services tutorials. We have now published what I call “quickstart completed” Mobile Apps samples for a .NET backend with Windows and Xamarin.Android clients. Of particular interest are the implementation decisions that were made when implementing offline, auth, and push at the same time. There are also some real-world extensions made in these project, like enabling the clients to add tags to their push registrations.

Parse server on Azure App Service

OK, this one’s not technically new, since I blogged about it last time—just wanted to include it for completeness sake. I should also mention that while the officially supported guidance for migrating Parse notifications to Azure Notification Hubs is still in the works, this post can help you get started now with Hubs (for those who can’t wait).

That’s all for now…

Cheers!

Glenn Gailey

While I was happy with the post overall, there was one nifty bit of work that didn’t get featured. As part of the effort, the team created a App Service deployment template, which is basically a hosted site for creating a new app service and deploying the Parse server from the GitHub repo to the new site all in a single step. (If you recall, creating a new app service took quite a few steps.) This deployment is triggered by the Deploy to Azure button, which you may have seen in other samples in the Azure repos. If you were wondering, the deployment is powered by Azure Resource Manager.

One of the best parts about the deploy button is that you can even pick the pricing tier for the newly created App Service plan as part of the template. Basically, the deploy button replaces these three manual sections in the original blog post:

• Create a new backend in App Service
• Clone the Parse server repo and deploy to Azure
• Configure the backend

Here’s the streamlined procedure using the Deploy to Azure button:

1. Fork the Azure Parse server example project in GitHub into your GitHub account, then click Deploy to Azure.
   
   This displays the Deploy to Azure wizard.
2. Complete the deployment template to create a new resource group. Choose a meaningful Site Name and Resource Group Name for your new web app, then click Next.
    
   In this template, SKU determines the pricing tier for the App Service plan for your resource group. Also, when you supply Mongo Connection String, Parse App ID and Parse Master Key values in this template, they become environment variables stored securely in App Service (not on your local machine or in a repo).
3. The deployment template confirms that you you are about to create and deploy a new web app based on the Parse server example repo. When you are ready, click Deploy.
   
   That’s it!
4. After deployment completes successfully, you will see the URL for your new service. Click Manage to navigate to your new backend in the Azure portal.
   
5. Click All settings > Application settings and scroll down the in the Application settings blade to App settings.
   
   Notice that the MongoDB and Parse keys you provided earlier are now are stored as app settings.

At this point, you can go back to the main procedure starting with Try out the Hello World. If you find any issues using the deployment button, please let the Azure team in in the Mobile forums.

Even cooler is that the Deploy to Azure button got accepted into the main ParsePlatform/parse-server-example repo:

This is pretty great stuff, and it’s awesome that it came together so fast. I’ve traditionally been mostly a .NET developer, but I have to say that there is something about an open and collaborative platform like Node.js where it seems like things can just get done faster.

Cheers!

Glenn Gailey 

Because the client can’t add tags and at the same time there is not service-side hooks into the push notification registration process, the client needs to do the work of adding new tags to a given registration. To let the client supply tags, we need to add an API to our mobile app backend that the client to call to add tags.

Before we dive into creating a new custom API, let’s briefly discuss the new installation ID concept, which is key to the whole thing. Also note that this post uses a .NET backend, but the same principles apply for a node.js backend.

Introducing InstallationId

The Mobile Apps client library now defines an installation ID, which didn’t exist in Mobile Services. The installation ID is a GUID that is specific to an installed app on a given mobile device, to the point that when you uninstall and reinstall the app on the same device you get a new GUID. The installation ID can be obtained from the Mobile client API, as follows:

MobileServiceClient.InstallationId;

This same API exists in the Mobile Apps library on all client device platforms. How this works is that when the client registers for push notifications with Notification Hubs (through the Mobile Apps client), this installation ID is added automatically as a tag. This tag is then used as an index into a specific registration, and the Notification Hubs client has new APIs that let you work with registrations based on this value.  Here is what an installation ID tag value looks like:

$InstallationId:{9c105281-c188-44b8-b1b5-8d08725c4785}

When working with the Notification Hubs client, all you will need is the GUID value, which you get from the MobileServiceClient.

The UpdateTags controller

To enable the client to add tags to its registration, the first thing I did was create a new ApiController named UpdateTagsController in my Mobile App backend, and in the initializer I added the standard code that creates the NotificationHubClient instance based on the hub used by my Mobile App backend:

private NotificationHubClient hubClient;

protected override void Initialize(HttpControllerContext controllerContext)
{
    base.Initialize(controllerContext);

    // Get the Mobile App settings.
    MobileAppSettingsDictionary settings =
        this.Configuration.GetMobileAppSettingsProvider().GetMobileAppSettings();

    // Get the Notification Hubs credentials for the Mobile App.
    string notificationHubName = settings.NotificationHubName;
    string notificationHubConnection = settings
        .Connections[MobileAppSettingsKeys.NotificationHubConnectionString]
        .ConnectionString;

    // Create the notification hub client.
    hubClient = NotificationHubClient
        .CreateClientFromConnectionString(notificationHubConnection, 
            notificationHubName);
}

Then I implemented a GET by ID method so that I could retrieve tags for a given installation ID:

// GET api/UpdateTags/Id
[HttpGet]
public async Task<List<string>> GetTagsByInstallationId(string Id)
{
    try
    {
        // Return the installation for the specific ID.
        var installation =  await hubClient.GetInstallationAsync(Id);
        return  installation.Tags as List<string>;
    }
    catch(MessagingException ex)
    {
        throw ex;
    }
}

In my scenario, the client didn’t really need to use this, but it would be useful to inspect existing tags, and I did use it when checking tags using a REST client, like fiddler. Here’s the HTTP GET request to the new API:

GET https://todolist.azurewebsites.net/api/updatetags/9c105281-c188-44b8-b1b5-8d08725c4785 HTTP/1.1
User-Agent: Fiddler
Host: todolist.azurewebsites.net
ZUMO-API-VERSION: 2.0.0

Then you get back the existing tags:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 82
Content-Type: application/json; charset=utf-8
Expires: 0
Server: Microsoft-IIS/8.0
X-Powered-By: ASP.NET
Date: Wed, 20 Jan 2016 21:13:15 GMT

["_UserId:sid:4fce9655d0610c53a1f236ae7befc14x"]

Note that the only tag returned is the user ID, because this registration we done with a logged-in user. The installation ID isn’t returned by the API, but you can see it there by using the Server Explorer in Visual Studio:

If your app needs to send notifications to a specific device, you probably want to store the installation ID from your user along with the user ID or some other tracking data in your backend.

Adding new tags: the POST method

The method mapped to the POST request expects a JSON array of tags from the client, which get added to the registration for a given installation ID. (If the input is not a valid JSON array, an exception returns an HTTP 500.) A single PartialUpdateOperation in a list contains the JArray of tags to be added (you can only have one tags operation in a given request to PatchInstallationAsync().

// POST api/UpdateTags/Id
[HttpPost]
public async Task<HttpResponseMessage> AddTagsToInstallation(string Id)
{
    // Get the tags to update from the body of the request.
    var message = await this.Request.Content.ReadAsStringAsync();

    // Validate the submitted tags.
    if (string.IsNullOrEmpty(message) || message.Contains("sid:"))
    {
        // We can't trust users to submit their own user IDs.
        return new HttpResponseMessage(HttpStatusCode.BadRequest);
    }

    // Verify that the tags are a valid JSON array.
    var tags = JArray.Parse(message);

    // Define a collection of PartialUpdateOperations. Note that 
    // only one '/tags' path is permitted in a given collection.
    var updates = new List<PartialUpdateOperation>();

    // Add a update operation for the tag.
    updates.Add(new PartialUpdateOperation
    {
        Operation = UpdateOperationType.Add,
        Path = "/tags",
        Value = tags.ToString()
    });

    try
    {
        // Add the requested tag to the installation.
        await hubClient.PatchInstallationAsync(Id, updates);

        // Return success status.
        return new HttpResponseMessage(HttpStatusCode.OK);
    }
    catch(MessagingException)
    {
        // When an error occurs, return a failure status.
        return new HttpResponseMessage(HttpStatusCode.InternalServerError);
    }
}

Here is an example of calling the POST method directly using a REST client, like Fiddler:

POST http://todolist.azurewebsites.net/api/updatetags/9c105281-c188-44b8-b1b5-8d08725c4785 HTTP/1.1
User-Agent: Fiddler
Host: localhost:51795
ZUMO-API-VERSION: 2.0.0
Content-Length: 20

['broadcast','test']

Next we will see how to call this new API from a .NET client app.

Calling the new API from the client

With the new API tested and published, it’s very easy to call it from the client app after registration is complete. The following code example calls InvokeApiAsync() on the MobileServiceClient after registration succeeds to send a two tag update request to the /api/updatetags/<installation_id> endpoint:

// Register for template push notifications.
await App.MobileService.GetPush()
.RegisterAsync(channel.Uri, templates);

// Define two new tags as a JSON array.
var body = new JArray();
body.Add("broadcast");
body.Add("test");

// Call the custom API '/api/updatetags/<installationid>' 
// with the JArray of tags.
var response = await App.MobileService
    .InvokeApiAsync("updatetags/" 
    + App.MobileService.InstallationId, body);

Now, you can send notifications only to specific devices depending on the registered tags.

Final thoughts

Well, that’s all there is to adding tags from to a registration using the installation ID from the client. Pretty easy stuff. Although you do need a valid installation ID to successfully call these APIs, you might want to also require authentication, just to keep any malicious users from trying to add tags using some randomly guessed installation ID.

Cheers!

Glenn Gailey

A JavaScript backend mobile service has essentially two parts: the node.js site and code that hooks that site to the Mobile Services runtime and Azure SQL Database. The node.js site files (script files, permissions, custom API endpoints) are easy to clone because they are defined in the site itself. Other actions, like creating the mobile service itself and tables within the mobile service, must either be done in the Azure classic portal or by using the command line interface (CLI). So, if you really want to automate the process of cloning and syncing a production and staging site, you will use the CLI and Git.

Configure the Git repo

Since we need to pull down the production site and copy those files to our new staging site, we need to make sure that Git publishing is configured on the mobile service. Complete the following steps with your production site:

1. Enable source control in your mobile service. 
2. Install Git and create the local repository.

Note that you only need to configure Git publishing once for your subscription. At this point, you should have pulled the production site down to the Git repo on your local machine.

Create the cloned mobile service

You need to create a new mobile service (such as todolist-clone) and recreate the same tables that you have in the production site. You can do this either in the portal or by using the CLI, like this:

1. Create the mobile service clone:

   azure mobile create todolist-clone <server-admin> <server-password>

2. Re-create the same tables (once for each existing table):

   azure mobile table create todolist-clone TodoItem

Overwrite the cloned mobile service and publish

Once the new cloned service is configured, you can copy over from the production site and republish:

1. Use Git to also create a local repository for the cloned site.
   Note that your credentials are the same as the first time—since they are shared across the subscription.
2. On your local machine, copy files from the \service subdirectory of the original production repo (todolist) to the same local directory in the new repo (todolist-clone).
3. Open the package.json file in the root of the cloned repo and update the name field to the name of the clone, as below:

   {
     "name": "todolist-clone",
     "version": "1.0.0",
     "description": "todolist-cordova - hosted on Windows Azure Mobile Services",
     "main": "server.js",
     "engines": {
       "node": ">= 0.8.19"
     },
     "dependencies": {
   	"node-uuid": "~1.4.3"
     },
     "devDependencies": {},
     "scripts": {},
     "author": "unknown",
     "licenses": [],
     "keywords":[]
   }

4. Save the changes and execute the following commands in the new repo to add/commit/publish changes:

   git add .

   git commit -a -m "cloned the site"

   git push origin master

At this point, the mobile service will be restarted and you should see your production APIs, script files, and permissions in the new cloned mobile service. Note that you won’t see your existing data, since the cloned service uses tables in a new DB schema that matches the service name (in this case todolist_clone).

Hope that this is helpful….

Cheers!

Glenn Gailey

As folks may remember, I published a Cordova push notifications sample for Azure to support my MSDN Magazine article: Microsoft Azure - Push Notifications to Cordova Apps with Microsoft Azure. It has been almost a year since I wrote that article (which was published in Jan 2015), and since then the article has gone out of date. Being used to writing for MSDN or azure.com, I was saddened to realize that I am not able to update this MSDN Magazine article as I can most other content on a microsoft.com web property. Fortunately, I am still able to update the sample project itself, which I have now done.

Updating the Project to Visual Studio 2015

The original sample (and article) was created using Apache Cordova Tools for Visual Studio 2013, which is no longer the happy path for Cordova apps using Visual Studio. There have been some significant (and breaking) changes to Cordova tools between 2013 and 2015, including re-rationalizing the Cordova project to become much more of a standard Cordova project, which you can now build using conventional Cordova command line tools. In fact, there are lots of CI options for VS Cordova projects now, as you can read about in the docs.

Anyway, I updated my project to Visual Studio 2015 and it’s now merged into the Mobile Services sample repository.

There’s a Cool New Push Plugin for Cordova/PhoneGap

While updating the sample, I discovered that the classic PushPlugin we’ve all been using to support push notifications on Cordova has been deprecated. There’s now a new push plugin, which you can find here: https://github.com/phonegap/phonegap-plugin-push

Needless to say, when I discovered this I also updated the sample to use this most recent (and supported) push plugin. I was happy to discover that the new plugin is much more platform agnostic than the old one way. By switching to the new plugin, I was also able to reduce the amount of code required for push by about 40% (103 lines to 61 lines of code). For example, here’s the code that initializes the plugin and requests the handle from either APNS or GCM:

pushNotification = PushNotification.init({
    "android": { "senderID": GCM_SENDER_ID },
    "ios": { "alert": "true", "badge": "false", "sound": "false" }
});

(Note that WNS is also supported by the plugin (just also pass "windows": {} to the init function), it’s just not supported by the Mobile Services plugin.)

The new plugin is event based, so you simply register for the registration and notification events. The registration handler is where you register with Notification Hubs using the handle. My client code here is still platform-specific because of the Mobile Services plugin:

pushNotification.on('registration', function (data) {
    // Get the native platform of the device.
    var platform = device.platform;
    // Get the handle returned during registration.
    var handle = data.registrationId;
    // Set the device-specific message template.
    if (platform == 'android' || platform == 'Android') {
        // Template registration.
        var template = '{ "data" : {"message":"$(message)"}}';
        // Register for notifications.
        mobileServiceClient.push.gcm.registerTemplate(handle,
            'myTemplate', template, null)
            .done(registrationSuccess, registrationFailure);
    } else if (device.platform === 'iOS') {
        // Template registration.
        var template = '{"aps": {"alert": "$(message)"}}';
        // Register for notifications.            
        mobileServiceClient.push.apns.registerTemplate(handle,
            'myTemplate', template, null)
            .done(registrationSuccess, registrationFailure);
    }
});

(There’s also a platform agnostic Cordova plugin for Notification Hubs, but it doesn’t support templates, which is a really nice to have for Cordova apps. )

In my sample, the notification event is handled the same way on all platforms:

pushNotification.on('notification', function (data) {
    // Display the alert message in an alert.
    alert(data.message);
    // Reload the items list.
    app.Storage.getData();
});

There are other fields on data, depending on the platform itself—you can check out the push plugin documentation for more info.

Overall impression: I’m not a JavaScript guru, but using this new plugin seems to yield much cleaner and more manageable code.

Whitelist Plugin is Now Required

One final thing that I discovered (and what hung me up the longest) is that the latest version of Cordova won’t connect to Azure using XHR requests. By working through the error messages, I figured out that I needed to use the Whitelist plugin and define, via policies, what code can run and what remote requests are allowed. Basically, I has to add this code to my index.html page to enable the app to connect to my mobile service:

<meta http-equiv="Content-Security-Policy" 
        content="connect-src 'self' https://*.azure-mobile.net;">

Hopefully, the updated sample will help get folks moving in the right direction again with Azure push notifications and Cordova apps.

Cheers!

Glenn Gailey

Updated: (10/27/15) Corrected my assessment of the new push plugin. You can read more about this plugin in my post Updates to My Cordova Push Sample and new Cordova Push Plugin.

Updated: (10/20/15) Added more information on sending push notifications from various backends.

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).
• Sending notification from the backend.

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

The original push notification plugin for Cordova, which does the basic work of requesting handles¹ and handling incoming notifications⁴, has been deprecated.  (The new version of the plugin is much more platform agnostic; I was also able to reduce the amount of code required for push by about 40%.)
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
• Pros: Supports all major platforms and is fairly platform-agnostic (at least from a client perspective).
• Cons: Doesn’t talk to any backend services. 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 Apps Cordova client

Azure App Service Mobile Apps now has (beta) Cordova support available, and is maintained by the Azure Mobile team.  This plugin supports registering with Notification Hubs² and is the way that Microsoft Azure wants you to add push notifications to your Cordova app. Note that offline sync support will be added to the plugin before GA.

• Supports: APNS, GCM, and WNS. 
• Pros: Integrates with Mobile Apps to enable Notification Hubs registration².
• Cons: You must use a Mobile Apps backend.

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².
• Cons: Only supports APNS and GCM. Still requires PushPlugin.^{1, 4}

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

Custom authentication sample

I was challenged by a customer via Twitter to publish a custom authentication project that includes both backend and universal Windows client (as I described in my previous post) but that also used Azure Table storage.

This sample demonstrates adding custom authentication to the TodoList quickstart mobile service .NET backend project. By default, this project uses Azure SQL Database for data storage, but the readme shows you how to convert storage to use Azure Table storage. This solution includes a universal Windows 8.1 project that is used to test the custom authentication in the mobile service.

Hybrid Connections tutorial for Mobile Apps

Like the ones for Mobile Services and Web Apps, this new tutorial shows you how to connect your Azure App Service mobile app to an on-premises SQL Server database by using Hybrid Connections.

Universal Windows version of Upload images to Azure Storage by using Mobile Services

It took a while to get this done, but the upload images tutorials are very popular. Now, there is a universal Windows 8.1 app version that uses the new MediaCapture APIs that support both Windows and Windows Phone devices. We are also working on the Android version now that the Azure Storage SDK for Android is available (stay tuned).

Xamarin.Forms version of the TodoList quickstart project

Xamarin.Forms is becoming more and more popular, but sadly we may never get an official Xamarin.Forms  version of the TodoList app quickstart that you can download from the portal for your mobile service. Luckily, our resident Xamarin expert, Norm Estabrook, wrote for us a Xamarin.Forms version of TodoList.

The good news is that there is already full quickstart support for Xamarin.Forms in Mobile Apps:

Add push notifications to your Xamarin.Forms app

Norm also added a nice Xamarin.Forms version of the Add push notifications to your app series of Mobile Services tutorials. The cool thing about this is that it’s a cross-platform tutorial that leverages template registrations in Notification Hubs to send simultaneous registrations to iOS (APNS), Android (GCM), and Windows (WNS) platforms. 

Next, I need to spend some time cleaning up the preview Mobile Apps topics.

Cheers!

Glenn Gailey

I spent some time the past few days improving the topic Add custom authentication to your app, which had a few issues—the main one being that we didn’t tell you how to consume the custom authentication endpoints in a client app to sign-in a user. The new section we added describes the steps needed to access the custom authentication endpoints from the client, which are:

1. Create a sign-in UI to get the username and password.
2. Create a new registration using the CustomRegistration endpoint.
3. Sign-in using the CustomLogin endpoint.
4. Use the returned user ID and authentication token to set the current user for the client.

This guidance we added to the topic is platform agnostic, so it lacks specific code examples. Fortunately, there are other examples of how to call a custom API from the various clients (Carlos’ blog post is still one of the best resources on calling custom APIs). In this post, I show how I did it for a Windows C# app.

Create the custom sign-in UI

The first step is to create a custom UI to supply the username and password, which should be done at runtime (you can cache these credentials, but you need to store them securely using PasswordVault, as shown in this topic).

Because I remember having to create these kinds of sign-in UIs all of the time in the Windows Forms days, I was surprised at how not straightforward it was to create a custom sign-in dialog in a modern Windows app. To me, this demonstrates the benefits of Mobile Services authentication, either client-directed authentication (using Live SDK) or service-directed authentication (which uses the WebAuthentiationBroker class under the covers), both are browser-based authentication so no extra UI is needed.

For my new Windows Store app sign-in UI, I decided to just add a new Grid that overlays the existing UI grid, which contains username and password fields. Here’s the XAML:

<Grid Name="GridLoginDialog" Background="Black" Visibility="Collapsed" 
      Opacity="0.5" >
    <Grid Width="350" Height="200" Background="White" Opacity="100">
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="*"/>
            <ColumnDefinition Width="200"/>
        </Grid.ColumnDefinitions>
        <Grid.RowDefinitions>
            <RowDefinition Height="35" />
            <RowDefinition Height="*" />
            <RowDefinition Height="*" />
            <RowDefinition Height="60" />
        </Grid.RowDefinitions>
        <TextBlock Name="loginMessage" />
        <TextBlock Grid.Row="1" Grid.Column="0" Text="Username: " 
                   HorizontalAlignment="Right" FontSize="12" 
                   VerticalAlignment="Center"  />
        <TextBox Grid.Row="1" Grid.Column="1" Name="txtUsername" 
                 HorizontalAlignment="Right" FontSize="12" 
                 VerticalAlignment="Center" />
        <TextBlock Grid.Row="2" Grid.Column="0"  Text="Password: "  />
        <PasswordBox Grid.Row="2" Grid.Column="1" Name="txtPassword" 
                     Margin="0,10,22,10" />
        <StackPanel Grid.Column="1" Grid.Row="3"  Orientation="Horizontal">
            <Button Content="Sign in" Width="90" Name="ButtonCustomLogin" 
                    Click="ButtonCustomLogin_Click" />
            <Button Content="Cancel" Width="90" Name="ButtonCancelLogin" 
                    Click="ButtonCancelLogin_Click" />                   
        </StackPanel>
        <ProgressRing Name="LoginProgress" IsActive="false" Grid.Column="0" 
                      Grid.Row="3" HorizontalAlignment="Stretch" 
                      VerticalAlignment="Stretch" Margin="2"/>
    </Grid>          
</Grid>

I added an explicit sign-in button, which when clicked displays my sign-in grid:

private void ButtonCustomLogin_Click(object sender, RoutedEventArgs e)
{
    // Show the sign-in grid and hide the login button.
    this.GridLoginDialog.Visibility = Visibility.Visible;
    this.ButtonCustomLogin.Visibility = Visibility.Collapsed;

}

Here’s how the UI looks:

Google/Bing turned up very little about custom sign-in UI for Windows Store apps, so this is what I came up with. If you know of a better pattern for how to do this, I would love to know about it (please leave me a comment).

Create a new registration

The custom authentication tutorial has you create a CustomRegistration endpoint, which is used to create a new user in the Accounts table. Frankly, this part of the topic makes me the most uneasy, especially since we tell you to set this endpoint to allow anonymous access. (This is the great thing about using identity providers like Facebook and Google with Mobile Services, at least these third-party services already have account provisioning figured out.) I added a note to this section strongly suggesting that you implement some kind of account validation scheme, such as sending a text or email with a confirmation code that the user can enter to complete registration. Or maybe, you make this an endpoint that requires a master key so that only someone with service level access can add accounts.

My client sample doesn’t do registration; I just assume that new account provisioning is done out-of-band, I actually changed the access permissions on my endpoint to [AuthorizeLevel(AuthorizationLevel.Admin)] and add registrations from the API help pages, using the service master key. While I don’t show how to access the CustomRegistration endpoint here, the code you need is nearly identical to the code used to access CustomLogin, which we will look at next.

Sign-in to the CustomLogin endpoint

Assuming that my user account is already provisioned, you just use the supplied username and password to call the CustomLogin API, with a POST request. This is done in the AuthenticateAsync method:

private async Task<MobileServiceUser> AuthenticateAsync(string username, 
    string password) {           

    // Call the CustomLogin API and set the returned MobileServiceUser
    // as the current user.
    var user = await App.MobileService
        .InvokeApiAsync<LoginRequest, MobileServiceUser>(
        "CustomLogin", new LoginRequest() { 
            UserName = username, 
            Password = password });

    return user;
}

Note that the InvokeApi<T,U> method, which by default calls the endpoint using a POST request, returns a MobileServiceUser object. This works because the shape of the response object returned by the CustomLogin endpoint is the same as the MobileServiceUser class, so the client library is able to deserialize it correctly from the response. Note that the original version of the custom authentication tutorial returned a system-defined LoginResult, which for some reason doesn’t quite match the shape of the client’s user object. When I updated the tutorial, I changed this to instead return a CustomLoginResult object, which does match MobileServiceUser and make it a bit easier to set the current user on the client.

Set the current user on the client

The final thing to do is to set the CurrentUser property on the MobileServiceClient instance to the MobileServiceUser returned by the successful CustomLogin request, as shown in the sign-in button code below:

private async void ButtonCustomLogin_Click(object sender, RoutedEventArgs e)
{
    if (string.IsNullOrEmpty(txtUsername.Text) 
        || string.IsNullOrEmpty(txtPassword.Password))
    {
        return;
    }

    this.LoginProgress.IsActive = true;

    try
    {
        // Sign-in and set the returned user on the context,
        // then load data from the mobile service.

App.MobileService.CurrentUser = await AuthenticateAsync(this.txtUsername.Text, txtPassword.Password);

        await RefreshTodoItems();
        this.GridLoginDialog.Visibility = Visibility.Collapsed;
    }
    catch (MobileServiceInvalidOperationException ex)
    {
        loginMessage.Text = ex.Message;        
    }
    finally
    {
        ResetLoginUI();
    }
}

Note that setting the current user on the client follows the same basic pattern for caching tokens shown in the client authentication tutorial. Also, I could have set the current user in the AuthenticateAsync method, but I wanted to break out this step for clarity.

With the user set, the Mobile Services client uses the authenticationToken in the current MobileServiceUser to generate the X-ZUMO-AUTH header, which enables access to table controller endpoints that are restricted to only authenticated users.

Yay! It works  

Final thoughts

Having only used the Mobile Service built-in authentication patterns, this was an interesting change of pace. Here are a few things other random things that occurred to me while I worked on this side project….

• Custom authentication is way harder than using the authentication support built into Azure Mobile Services. But, isn’t that why you are willing to pay a little bit extra for Mobile Services (that and the native client libraries…and push notifications). With the built-in authentiation support, once you get everything configured (which requires almost no code at all) you simply call LoginAsync from the client and you are done.
• With custom authentication you are on your own. The tutorial we provide for a .NET backend (as well as Josh’s blog post using node.js) are really bare bones, you still need to harden your authentication endpoints, prevent spoofers and fraudulent registrations, etc. To be honest, I’m not really an expert on security programming. If you are, have at it. Maybe you have done this before and feel confident with it. However, if (like me) you are new to this—get an expert to review what you are doing before you go into production with any custom authentication scheme.
• One of the many benefits of using our Mobile Services client libraries, aside from the ease and convenience, is that they always make requests to your mobile service running in Azure by using HTTPS. This means that InvokeApi will always use an HTTPS request. Using a pure REST call, you need to make sure you are accessing the endpoint using HTTPS.

Anyway, please let us know via Disqus if you have any questions or issues with the Custom Authentication tutorial.

Cheers!

Glenn Gailey