• Article

April 2015

Volume 30 Number 4

Microsoft Azure - Azure Notification Hubs: Best Practices for Managing Devices

By Sara Silva

The mobile applications market is growing faster and faster, and improving the UX of any application is crucial because it increases user loyalty. One of the most important features of modern applications is that they can be kept alive, which means keeping the user informed about the latest events that have occurred in the application, even when it’s not being used. This is possible through push notifications.

Each mobile platform has its own push notification service (PNS) responsible for pushing the notifications—short messages—to the device. Windows applications allow apps to receive different push notification types that represent different ways to display the message: toast, tile, raw and badge. For Android applications, on the other hand, only a key/value message is sent to the device and the layout is defined in the application by the class responsible for managing push notifications. In Apple iOS applications, the process is a mix of these approaches.

The PNS delivers the notifications, though each application needs a back end or a Web or desktop application to define the message and to connect to the push notification provider to send it. 

Azure Notification Hubs is a Microsoft Azure service that provides an easy-to-use infrastructure for sending push notifications from any back end to any mobile platform. Actually, there are two main patterns and two models for managing devices in Notification Hubs. In this article I’ll show how each pattern should be used; discuss the advantages, disadvantages and possible scenarios for each; and describe the different models that can be used. I’ll focus on best practices for sending cross-platform and customized push notifications using Notification Hubs, and also show how Notification Hubs is integrated into Azure Mobile Services.

The Push Notification Lifecycle

The push notification lifecycle consists of three main steps:

  1. The application makes a request for the push notification service handle, which can be a token, channel URI or a registrationId, depending on the mobile platform.
  2. The application sends the PNS handle to the back end to store it.
  3. The back end sends a request to the PNS, which then delivers the push notification.

Conceptually this process is very simple, but in practice it’s not so easy because the infrastructure required to implement this flow is complex. If an application is provided for different client platforms, it requires an implementation for each one (in reality, it will represent an implementation for each interface provided by each platform). Moreover, the format for each push notification has its own platform specifications and, in the end, these can be hard to maintain. And that’s not all: The back end needs to be able to scale some push notification services that don’t support broadcasting to multiple devices; to target push notifications to different interest groups; and monitor the push notifications for delivery status. These issues must be handled in the back end and, consequently, this requires a complex infrastructure.

Using Notification Hubs

As I noted, Azure Notification Hubs makes it easy to send mobile push notifications from any back end to any mobile platform, and it supports sending push notifications for different interest groups and providing monitoring, telemetry and scheduling of push notifications. In this way, Notification Hubs is a third-party service that helps send cross-platform and personalized push notifications to applications and implements all the needs of a push notification infrastructure.

To integrate Notification Hubs in an application requires configuration in the Azure Portal; the connection between Notification Hubs and the PNS should be configured in the Configuration separator of the respective Notification Hub. Without these configurations, push notifications can’t be sent and an error will occur. (If you’re ever in doubt about which push notification services are supported by Notification Hubs, the Configuration separator is the best place to check.) To use Notification Hubs, you’ll need to understand tags, templates and the different ways Notification Hubs can be used.

In general, a tag represents an interest group, which allows you to send push notifications to specific targets. For example, a sports news application could define tags for each sport: cycling, football, tennis and so forth, allowing the user to select what he wants to receive based on his interests. For cases where authentication is required and the focus is the user, the user id can be used as the tag. In practice, a tag is no more than a simple string value (like “cycling,” “football” or “tennis”), and it’s also useful for localization (for different languages there’s a pattern like “en_cycling” or “pt_cycling,” which represents tags in English or Portuguese, respectively).

Templates aren’t a new concept, but Notification Hubs creates an abstraction that allows you to define either platform-specific templates or generic templates, which means you can specify key/value pairs for each push notification defined when the device is registered. The registration will then provide a native notification (toast, payload or message) that contains expressions (such as $(message)) with a value the back end or application will define when the push notification is sent.

Figure 1 shows examples of the generic template (for Windows, iOS and Android) using expressions.

Figure 1 Generic Templates

var toast = new XElement("toast", 
  new XElement("visual",
  new XElement("binding",
  new XAttribute("template", "ToastText01"),
  new XElement("text",
  new XAttribute("id", "1"),                                
  "$(message)")))).ToString(SaveOptions.DisableFormatting);
var alert = new JObject(
  new JProperty("aps", new JObject(new JProperty("alert", "$(message)"))),
  new JProperty("inAppMessage", notificationText))
  .ToString(Newtonsoft.Json.Formatting.None);
var payload = new JObject(
  new JProperty("data", new JObject(new JProperty("message", "$(message)"))))
  .ToString(Newtonsoft.Json.Formatting.None);

The back end or application will fill the value when it sends the key/value (Figure 2 illustrates the process):

{"message", "Message here!"}

Sending a Platform-Independent Message
Figure 2 Sending a Platform-Independent Message

Registering Devices

In mobile development using Notification Hubs, there are two patterns for managing devices and sending push notifications, which can use two different models. In general, the patterns can be described as follows:

Case 1:  Devices connect directly to Notification Hubs

  • The client application connects directly to Notification Hubs to register the device.
  • The back end or a Web or desktop application connects to Notification Hubs to send the push notification.
  • The PNS will deliver the mobile push notification.

Case 2: The back end manages devices in Notification Hubs

  • The client application connects to the back end.
  • The back end connects with Notification Hubs to register the devices.
  • The back end defines the push notification, which will be sent by Notification Hubs.
  • The PNS will distribute the mobile push notification.

Both patterns allow you to use either the Registration model or the Installation model; these models describe the way a device sends the required information to the notification hub. The Installation model was introduced recently and is recommended for new applications or even for current applications. This new model doesn’t make the Registration model obsolete. Here’s a general description of each model:

Registration model: In this model, the application sends a registration request to the Notification Hub, providing the PNS handler and tags, and the hub returns a registration id. For each registration you can choose a native template or a generic template, which will define the message.

Installation model: In this model, the application sends an installation request to the Notification Hub, providing all information required for the process: InstallationId (for example, a GUID), tags, PNS handler, templates and secondary templates (for Windows apps).

Although both models are currently available for use, the Installation model was introduced for certain technical reasons, including:

  • The installation model is easier to implement and maintain.
  • The installation model allows partial updates to modify, add or remove tags, PNS handlers, templates, and so forth, without sending the Installation object; in contrast, the registration model requires the entire registration object.
  • The registration model introduces the possibility of duplicate registrations in the back end for the same device.
  • The registration model creates complexities in maintaining the list of registrations.
  • No matter which pattern you use, the flow will be the same.

The Installation model can be used in any .NET or Java back end with the Notification Hubs .NET and Java SDKs. For client applications, you can use the REST API with this model, until the new NuGet package that will support the installation model is released. You’ll find the current NuGet package with support for the registration model, WindowsAzure.Messaging.Managed, available at bit.ly/1ArIiIK.

Now, let’s take a look at the two patterns.

Case 1:  Devices Connect Directly to Notification Hubs

I’m going to discuss what happens when devices connect directly to Notification Hubs as this is the pattern most frequently used by developers. To describe this, I’ll use the registration model.

Registering and unregistering a device in Notification Hubs: The device requests a PNS handle from the PNS, then it connects to a Notification Hub to register, using the PNS handle. The Notification Hub uses this value in the PNS connection.

In practice, for example with Universal Applications, the application starts by requesting the channel from the Windows push notification service (WNS) with the following code:

// Get the channel from the application
var pushNotificationChannel =
  await PushNotificationChannelManager.
  CreatePushNotificationChannelForApplicationAsync();

For Android, Google Cloud Messaging provides a registrationId, and for iOS, the Apple Push Notification Service provides a token.

A Notification Hub object should be created using the hub name, defined in the Azure Portal, and the connection string (more specifically, the DefaultListenSharedAccessSignature key):

// Create the notification hub object
var hub = new NotificationHub(HubName, ConnectionString);

Note that the NotificationHub class is provided by the Windows­Azure.Messaging.Managed NuGet package (bit.ly/1ArIiIK).

Now the application can be registered with the Notification Hub:

// Register the device in Notification Hubs
var result =
  await hub.RegisterNativeAsync(pushNotificationChannel.Uri, Tags);

When you register a device in Notification Hubs, you don’t have to provide a list of tags, but if the application needs to define interest groups, those tags should be stored in the device to use them in a registration update.

Note that the result.RegistrationId received is the id of the registration in Notification Hubs and should not be confused with the registrationId used in Android applications (the id from Google Cloud Messaging).

Sending the push notification: The back end (or an application) connects to the Notification Hub to send the push notification, which can be sent to specific tags (or not) using a specific or generic template.

In this case, it’s not important who will connect to the Notification Hub, the back end or a Web or desktop application to send the notification. In practice, a NotificationHubClient object should be created and it will require the hub name, defined in the Azure Portal, and the connection string (more specifically, the DefaultFullSharedAccessSignature key):

// Create the Notification Hub client object
var hub = NotificationHubClient.CreateClientFromConnectionString(
  HubName, ConnectionString);

Next, the native push notification must be defined, for example, as shown in Figure 3.

Figure 3 Defining the Native Push Notification

// Define template for Windows
var toast =
  new XElement("toast",
  new XElement("visual",
  new XElement("binding",
  new XAttribute("template", "ToastText01"),
  new XElement("text",
  new XAttribute("id", "1"),
  notificationText)))).ToString(SaveOptions.DisableFormatting);
// Define template for iOS
var alert = new JObject(
  new JProperty("aps", new JObject(new JProperty("alert", notificationText))),
  new JProperty("inAppMessage", notificationText))
  .ToString(Newtonsoft.Json.Formatting.None);
// Define template for Android
var payload = new JObject(
  new JProperty("data", new JObject(new JProperty("message", notificationText)))
  .ToString(Newtonsoft.Json.Formatting.None);

And then the push notification can be sent:

var googleResult =
  await hub.SendGcmNativeNotificationAsync(payload, tags);
var windowsResult =
  await hub.SendWindowsNativeNotificationAsync(toast, tags;
var appleResult =
  await hub.SendAppleNativeNotificationAsync(alert, tags);

Whenever a mobile push notification is sent, a list of tags can be provided, but this is optional (it depends on the application requirements).

Distributing the push notification: To finish the process, the PNS delivers the notification to devices. The service will try to push the notification during a limited period of time, which varies for each service.

One of the advantages of this scenario is that it doesn’t require a back end, but there’s a disadvantage when a user uses more than one device: The tags aren’t shared among devices and the user needs to redefine the tags for each one. The mobile application depends on the Notification Hub, and it’s needed each time to update the tags in the application, which can be a problem if the user doesn’t update to the latest version (a common problem with mobile applications).

Possible scenarios for this case can include:

  • The mobile application doesn’t require a back end, such as when push notifications are sent by a desktop application with this capacity or by the back office (the admin Web site). For example, consider an application based on an online tech event’s news feed that has a settings page where users can subscribe to their interests, such as Developer Events, IT Pro Events and so on.  Once the interests are selected, the user will receive push notifications for those interests. Instead of requiring a back end to trigger push notifications, a desktop application or back office can talk directly to the Notification Hub whenever a new event is created to trigger push notifications to all devices that have subscribed to the specific interest.
  • The mobile application uses a back end, but the push notifications, for some reason, are not integrated in the services and are sent by a desktop application or by the back office. An example might be a client that has a service that provides information to show in the application, but doesn’t allow changes to the service (which can be used by different applications). However, to support push notifications, the client can send notifications using the back office, or even a desktop application.

Case 2:  The Back End Manages Devices in Notification Hubs

To describe this pattern I’ll use the new approach based on the installa­tion model, introduced recently by the Notification Hubs team.

The application connects to the back end: In this case, the application connects to the back end to create or update the installation object, which will be stored locally.

The device requests the PNS handle from the PNS and gets the last Installation from the Notification Hub, stored on the device. The device then connects to the back end to create or update the installation, from the device, in the Notification Hub. (A new Installation object will be created the first time, but it should be reused each time the back end connects with the Notification Hub for the same device.)

For example, in Universal Applications, the application will start by requesting the channel URI from the WNS, with the following:

// Get the channel from the application
var pushNotificationChannel =
  await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();

Before making the request to the back end to create or update the installation, the Installation object must be defined:

// Retrieve installation from local storage and
// create new one if it does not exist
var installation = SettingsHelper.Installation;
if (installation == null)
{
  installation = new Installation
  {
    InstallationId = Guid.NewGuid().ToString(),
    Platform = NotificationPlatform.Wns,
    PushChannel = pushNotificationChannel.ToString(),
    Tags = new List<string> {“news", "sports"}
  };
}

The installation class used in the client application is created from the JSON provided in the documentation.

At this point, you can request the registration with code like this:

// Create a client to send the HTTP registration request
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, new Uri(_registerUri))
{
  Content = new StringContent(JsonConvert.SerializeObject(installation),
    Encoding.UTF8, "application/json")
};
var response = await client.SendAsync(request);

The back end creates or updates the installation from the device, in the Notification Hub: When the back end receives a request to register the device using the installation model, it connects with the Notification Hub to create or update the installation. For example, in ASP.NET Web API, you can create a NotificationHubController to define the services to manage devices in Notification Hubs. The implementation requires a Notification Hub client object, which can be defined in the constructor, as follows:

public class NotificationHubController : ApiController
{
  private readonly NotificationHubClient _notificationHubClient;
  private const string HubName = "<define the notification hub name>";
  private const string ConnectionString = "<define the connection string>"
  public NotificationHubController()
  {
    _notificationHubClient =
      NotificationHubClient.CreateClientFromConnectionString(
      ConnectionString, HubName);
  }

Now you can write the method that will create or update the installation, which will receive as input the installation object, like so:

[HttpPost]
[Route("api/NH/CreateOrUpdate")]
public async Task CreateOrUpdateAsync(Installation installation)
{
  // Before creating or updating the installation is possible, 
  // you must change the tags to have secure tags
  await _notificationHubClient.
    CreateOrUpdateInstallationAsync(installation);
}

Note that the tags can be defined and stored in the back end (in both models). The mobile application isn’t required to store them or even know about them. For example, consider a bank application that defines tags for each account for a client. When an operation is done for an account, a push notification is sent to the device for that account. In this case, the tags must be secure and only the back end will know them.

In the Installation model, the installation will be stored in the Notification Hub, which means it can be retrieved based on the InstallationId.

The back end defines the push notification, which will be sent by the Notification Hub: The back end is responsible for sending the push notification to the Notification Hub, and you can provide tags and define the template for each platform (when a generic template isn’t defined).

The implementation is similar to the scenario in Case 1, where the back end or an application connects to the Notification Hub to send the push notification, so I won’t provide any additional code for this case.

By the way, in the installation model, it’s possible to send a push notification to a specific installation. This is a new feature only for registrations based on the Installation model. Here’s the code to do that:

_notificationHubClient.SendWindowsNativeNotificationAsync(
  payload, "$InstallationId:{" + installationId + "}");

The push notification service will distribute the push notification: To finish the process, the PNS will deliver the push notifications to the devices, during a limited period.

One of the advantages of this case is that tags can be static or dynamic, which means they can change anytime without changing or affecting the mobile applications; tags are secure because each user can only be registered for a tag if he is authenticated; tags can be shared among different devices for the same user; the mobile application is completely independent of Notification Hubs. The disadvantage of this case is the fact the process is more complex than the first case, if the registration model is used.

Possible scenarios for this include:

  • A mobile application that connects to a back end and the tags must be secure. A good example for this case is an application related to bank accounts, which supports push notifications to keep users informed about transactions in their accounts.
  • A mobile application that connects to a back end and tags must be dynamic. Consider an application that provides information for different music events, using tags to define different events, and for each event users can subscribe to be updated about all related information. The lifecycle for each tag is short and each time a new event is created, a new tag is created for that event. Tags, therefore, are dynamic and can be managed by the back end, keeping the process independent of the mobile application.

In both scenarios, tags should be stored in the back end, but that doesn’t mean the mobile client isn’t aware of them.

Updating Registrations

With the registration model, each time you want to update anything related to the registration, such as the tags being used, you must redo the registration; this is required to complete the update. But in the Installation model, you can update just specific details. This means if the application needs to update one tag, the templates or other details, it’s possible to do a partial update. Here’s the code for updating a tag:

// Define the partial update
PartialUpdateOperation replaceTagsOperation =
  new PartialUpdateOperation();
replaceTagsOperation.Operation = UpdateOperationType.Replace;
replaceTagsOperation.Path = "/tags/tennis";
replaceTagsOperation.Value = "cycling";
partialUpdates.Add(replaceTagsOperation);
// Send the partial update
_notificationHubClient.PatchInstallation(
  installationId, partialUpdates);

Using Notification Hubs in Azure Mobile Services

Azure Mobile Services allows you to develop an application with a scalable and secure back end (using the Microsoft .NET Framework or Node.js) hosted in Azure. With the focus on mobile applications, Azure Mobile Services provides the main features a mobile application needs, such as CRUD operations, social network authentication, offline support, push notifications and more.

Push notifications are provided in Azure Mobile Services by Notification Hubs, and each time an Azure Mobile Service is created, a Notification Hub is created and associated with the Azure Mobile Service.

Mobile applications that use Azure Mobile Services can implement push notifications in a quick and easy way, because the Azure Mobile Services SDK provides APIs for:

  • Client applications to register devices using the back end.
  • A back end to manage the devices in a Notification Hub; to modify requests from devices, which means the back end can add, modify or delete tags from the request made by mobile applications, or even cancel the registration; to send push notifications (using a specific template and, if tags are required, provide them).

The implementation in the .NET back end will be something similar to:

await Services.Push.SendAsync(
  GetWindowsPushMessageForToastText01(
  "My push notification message", tags));

The method GetWindowsPushMessageForToastText01 defines the template for the push notification based on a message, and can be implemented as shown in Figure 4.

Figure 4 Defining a WindowsPushMessage Based on the ToastText01 Template

public static IPushMessage GetWindowsPushMessageForToastText01(string message)
{
  var payload = new XElement("toast",
    new XElement("visual",
    new XElement("binding",
    new XAttribute("template", "ToastText01"),
    new XElement("text",
    new XAttribute("id", "1"), message))))
    .ToString(SaveOptions.DisableFormatting);
    return new WindowsPushMessage
    {
      XmlPayload = payload
    };
}

In the client application, for example in Universal Apps, you must request the channel from WNS:

// Get the channel
var channel =
  await PushNotificationChannelManager.
  CreatePushNotificationChannelForApplicationAsync();

Then the mobile service client should be created, and it will allow interaction with the back end:

// Create the MobileServiceClient using the
// AzureEndpoint and admin key
var mobileServiceClient =
  new Microsoft.WindowsAzure.MobileServices.MobileServiceClient(
  AzureEndPoint, AzureMobileServiceApplicationKey);

The AzureEndPoint should be something like https://mymobileservice.azure-mobile.net/ and the AzureMobileService­ApplicationKey is a string that represents the application key defined in the Azure Portal.

You can use the method RegisterNativeAsync to register a device, as follows:

// Register the device
await MobileServiceClient.Client.GetPush().RegisterNativeAsync(
  channel.Uri, tags);

But if you’re going to register the device using a generic template, use the RegisterTemplateAsync method.

In Azure Mobile Services (.NET back end), to extend, modify or cancel the registration for Azure Notification Hubs, the INotificationHandler interface should be implemented. By doing so, you can, for example, have secure tags.

Wrapping Up

Notification Hubs provides an abstraction to send push notifications from any back end to any mobile platform, and the new model allows you to define a unique installation that contains the essential information required by Notification Hubs. That installation can be reused, avoiding duplicate registration and complexity, for new applications or even in current applications, the installation model is recommended. There are two main patterns for registering devices to Notifications Hubs, which should be chosen according to the application requirements.

This model lets you send messages focused on specific interest groups using tags, and it’s also possible to define generic or specific templates and to scale and monitor the service according to the needs of the application. Finally, easy-to-use SDKs are provided in several languages for both the mobile apps and the back end.

 Notification Hubs integrated by default, which is a plus for developers because it enables implementation of the push notification feature in a quick and easy way.

Sara Silva is a mathematics graduate and Microsoft MVP. Nowadays, she works as a mobile developer in Portugal, with a main focus on Windows applications, Xamarin and Microsoft Azure. She blogs at saramgsilva.com and can be followed on Twitter at twitter.com/saramgsilva.

Thanks to the following Microsoft technical experts for reviewing this article: Piyush Joshi, Paulo Morgado and Chris Risner