SALES: 1-800-867-1380

Migrate a Mobile Service to use Notification Hubs

Updated: February 20, 2014

Your Windows Azure Mobile Services app uses a series of Node.js modules to send push notifications to the various platforms:

  • APN (for iOS)

  • WNS (for Windows Store)

  • Dpush (for Android)

  • MPNS (for Windows Phone)

These modules are accessed through the push object, in which Mobile Services instantiates them with the credentials configured in the portal.

When you upgrade to push notifications powered by Notification Hubs, your mobile service has the following major differences:

  1. The push object is an instance of NotificationHubService from the Windows Azure SDK for Node.js. This instance is configured to connect with the hub that has been created for your Mobile Service and that contains all the required push credentials (still configured through the portal).

    noteNote
    The only difference is that the callback parameter is changed to follow the Mobile Services convention of separated success and error callbacks.

  2. While the methods to send push notifications are very similar to the previously mentioned node, modulespreviNotificationHubs does not allow you to send to a platform-specific handle (for example, ChannelURIs, device tokens, or registrationids); rather it requires you to specify a target tag, that is obtained when a device registers. For more information about tags, see this article.

The following table proposes a set of analogies that helps to translate a design that uses MS push without Notification Hubs, to a design that does make use of it. Most importantly, no Channels table is needed.

 

MS without Notification Hub MS with Notification Hub Notes

Insert in Channels table

Register from the client SDK

MS will register the device into the hub and automatically add the client’s installation ID to the tags

Push to channel

Push to installation_id tag

Query to get the target channels (e.g. find all CannelURIs of people interested in Yankees updates)

Add/remove tags to device registrations, in one of two ways:

  1. If it depends on the client, call Register again (note that all tags are going to be overwritten)

  1. If it must occur in a script, use the push object to obtain the registration (using the installation_id tag) add/remove tags and then update

Note that when the query is very dynamic, it might be better to still query the database and retrieve a set of installation ids

For loop to push to a set of channels

Push to tag

Manage feedback from notification systems to remove expired channels

Automatically handled by notification hubs

Note that when using MS with Notification Hubs, you cannot read the Apple feedback channel from any other part of your application, as it may result in a violation of the Apple guidelines for push notifications.

When using Notification Hubs, expired tokens are automatically retrieved from Apple and the corresponding registrations expire. This means that if your app was performing some other operation when retrieving expired channels, it will be unable to continue.

Usually, the feedback channel is used to delete or mark users that abandoned the app. One way to approach this problem is to make sure to write a last logged-in value in your users table, and use a scheduler job to periodically delete or mark inactive users.

For all new services (or services adding push notifications) we strongly recommend that you take advantage of Notification Hubs push notifications. If you already have a Mobile Service in production, you have the following options.

You can continue to use the current Mobile Service push infrastructure and, if you need to use advanced features such as broadcast, advanced targeting or per-device personalization, you can still use a Notification Hub directly, as explained in this topic. The advantage to this method is that there is no change or compatibility break in your app. The disadvantages involve the maintenance of two different push engines, and you cannot use a Mobile Services original push and a Notification Hub together when sending to Apple devices (the feedback channel will not be handled properly).

If it is acceptable to force your users to update your app in order to continue receiving push notifications, the clean break migration makes it very easy to start taking advantage of all that the Notification Hubs integration has to offer.

To perform a clean break migration you must do the following:

  1. Stop pushing to old clients; for example, comment out all calls to push objects in your scripts.

  2. Enable enhanced push with Notification Hubs on your Mobile Service (this will change the behavior of the push object).

  3. Release a new client version that registers for push notifications instead of inserting the ChannelURI/device token/registration id in a table.

  4. Update your Mobile Service scripts to push again.

The advantages to this approach are an easy migration strategy and a single feature-rich push infrastructure. The disadvantage is that the client app requires an update to continue receiving push notifications.

If you must continue sending push notifications to older clients, and at the same time want to migrate to the Notification Hubs-based push infrastructure, you can build a solution that uses the old push infrastructure for older clients and the Notification Hub for your new clients.

ImportantImportant
The hybrid strategy does not work for Apple clients. When your Mobile Service starts using Notification Hubs, the feedback channel will be collected by the Notification Hub, and it is not possible to correctly maintain a table with device tokens in your Mobile Service. This problem does not exist for Android and Windows Store/Phone clients.

To use the hybrid strategy, do the following:

  1. Update service to autodetect the Notification Hubs presence and use the correct modules to use the legacy push infrastructure (see next section).

  2. Migrate service to use Notification Hubs.

  3. Release new clients that

    1. Continue updating the Channels table with a Boolean flag representing the fact that they are registered on Notification Hubs, or

    2. Register with the Notification Hub.

  4. When pushing,

    1. Check on the Channels table to see if the client is registered with Notification Hubs.

    2. Use the legacy push infrastructure -- if flag is false; push to the installation_id tag using the new push object if the flag is true. See the next section for a code example.

    3. You can start using Notification Hubs advanced features but they will only reach your new clients.

You can devise variations of the hybrid strategy depending on how you store ChannelURIs and GCM registration ids.

The advantages to this approach are that there is no required client update, and you also have the ability to use all Notification Hubs push features for new clients. The disadvantages of course, are that there is more migration work involved, and this approach does not work at all for Apple clients.

The main idea is to manually create a new instance of the legacy node module.

As explained in the previous section, you will not be able to use the APNS module in a Mobile Service that is using a Notification Hub, as they will compete for access on the feedback channel, and potentially result in a violation of the Apple guidelines for push notifications.

Since the push credentials are stored in the Notification Hub, you will have to reenter them as application config. To do this, go to the Configure tab in the portal and insert your PackageSID ad Client Secret as properties WNS_CLIENT_ID and WNS_CLIENT_SECRET, respectively.

Subsequently, each time you use push.wns in your script, you must add the following function, substituting the push.wns.send* call with the following:

var legacyWns = require('wns');
wns.send*();

Note that the callback structure of the node modules is different than that of the original Mobile Service module. For example:

 

Old call Using Node module
push.wns.sendToastText01(uri, {
        text1: "Sample toast"
    }, {
success: function (response) {
// success code
},
error: function(error) {
// error handling
}
});
legacyWns.sendToastText01(uri, {
        text1: "Sample toast"
    }, function (error, response) {
if (!error) {
// success code
} else {
// error handling
}
});

Similar to WNS, you must put your GCM ApiKey in your application settings, as explained above. You can call it GCM_APIKEY. The code appears as follows:

 

Old call Using Node module
push.gcm.send(regId, "Hello!", {
success: function (response) {
// success code
},
error: function(error) {
// error handling
}
});
var legacyGcm = require('dpush');
legacyGcm.send(process.env.GCM_APIKEY, regId, "Hello!", function (error, response) {
if (!error) {
// success code
} else {
// error handling
}
});

MPNS is easier, because the Mobile Service did not support authenticated push. When using MPNS, you can perform the following substitutions:

 

Old call Using Node module
push.mpns.sendFlipTile(uri, { 
title: item.text
    }, {
success: function (response) {
// success code
},
error: function(error) {
// error handling
}
});
var legacyMpns = require('mpns');
legacyMpns.sendFlipTile(uri, { 
title: item.text
    }, function (error, response) {
if (!error) {
// success code
} else {
// error handling
}
});

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft