Registration Management

This topic explains how to register devices to notification hubs in order to receive push notifications. The topic describes registrations at a high level, then introduces the two main patterns for registering devices: registering from the device directly to the notification hub, and registering through the application backend.

What is a Device Registration

A registration is a sub-entity of a notification hub, and associates a device PNS handle (a Platform Notification Service handle, for example, ChannelURI, device token, GCM registrationId) with tags and possibly a template. Tags are used to route notifications to the correct set of device handles. For more information, see Routing and Tag Expressions. Templates are used to implement per-registration transformation. For more information, see Templates.

It is important to note that registrations are transient. Similar to the PNS handles that they contain, registrations expire. You can set the time to live for a registration on the Notification Hub, up to a maximum of 90 days. This limit means that they must be periodically refreshed, and also that they should not be the only store for important information. This automatic expiration also simplifies cleanup when your mobile application is uninstalled.

Registrations must contain the most recent PNS handle for each device/channel. Because PNS handles can only be obtained in the client app on the device, one way to manage registrations is directly on that client app. On the other hand, security considerations and business logic related to tags might require you to manage the registration in the app back-end. The following section describes these two approaches.

Registration Management From the Device

When managing registrations from client apps, the backend is only responsible for sending notifications. Client apps keep the PNS handles up to date, and register to tags. The following picture illustrates this pattern.

The device first retrieves the PNS handle from the PNS, then registers with the notification hub directly. After the registration is successful, the app backend can send a notification targeting that registration. For more information about how to send notifications, see Routing and Tag Expressions.

Note that in this case, you will use only Listen rights to access your notification hubs from the device. For more information, see Security.

The following code registers your device using Notification Hubs API References:

await hub.RegisterNativeAsync(channelUri, tags);

[hub registerNativeWithDeviceToken:deviceToken tags:nil completion:^(NSError* error) {
    if (error != nil) {
        NSLog(@"Error registering for notifications: %@", error);
    }
}];

hub.register(regid, tags);

These methods create or update a registration for the device on which they are called. This means that in order to update the handle or the tags, you must overwrite the entire registration. Remember that registrations are transient, so you should always have a reliable store (either local storage on the device or in your app back-end) with the current tags that a specific device needs. See the Breaking News tutorial for more detailed examples of how to update registrations.

You can also use the REST APIs to register from the device. For more information, see How to Use the Notification Hubs REST Interface.

The following scenario tutorials provide step-by-step guidance on registering from your client:

• Getting Started with Notification Hubs

• Breaking News

Templates

If you want to use Templates, each registration represents an individual template. This means that if your device uses two templates, you must register each template independently with its own PNS handle and set of tags.

For native registrations (that is, without a template), registration methods for templates create or update existing registrations. To target different templates, you provide a template name when registering. You will provide different names if you want to maintain multiple templates for the same device.

The following code registers your device using Notification Hubs API References:

await hub.RegisterTemplateAsync(channelUri, template, templateName, tags);

[hub registerTemplateWithDeviceToken:deviceToken name:templateName jsonBodyTemplate: template expiryTemplate:nil tags:nil completion:^(NSError* error) {
    if (error != nil) {
        NSLog(@"Error registering for notifications: %@", error);
    }
}];

hub.registerTemplate(regId, templateName, template, tags);

Note that each registration call provides, in addition to the PNS handle and the optional set of tags, a template for the body of the notification and a name for the template. Moreover, each platform can have additional properties that are part of the template. In the case of Windows Store (using WNS) and Windows Phone 8 (using MPNS), an additional set of headers can be part of the template. In the case of APNs, you can set an expiry property to either a constant or to a template expression.

For instructions on how to modify these template fields, see API References or Notification Hubs REST APIs.

Secondary Tiles for Windows Store Apps

For Windows Store client applications, sending notifications to secondary tiles is the same as sending them to the primary one. Both native and template registrations are supported. The only difference is that secondary tiles have a different ChannelUri, which the SDK on your client app handles transparently.

At a high level, all the information provided in the previous sections work with secondary tiles by calling the corresponding methods on the objects exposed on the dictionary property Microsoft.WindowsAzure.Messaging.NotificationHub.SecondaryTiles. For example:

await hub.SecondaryTiles["myTileId"].RegisterNativeAsync(new string[] {"Yankees"});
await hub.SecondaryTiles["myTileId"].RegisterTemplateAsync(buildToastTemplate(), "toastTemplate", new string[] {"RedSox"});

The SecondaryTiles dictionary uses the same TileId that is used to create the SecondaryTiles object in your Windows Store app.

As with the primary ChannelUri, ChannelUris of secondary tiles can change at any moment. In order to keep the client app registrations in the notification hub updated, the device must refresh them with the current ChannelUris of the secondary tiles.

Drawbacks of Registering from the Device

Registering from the device is the simplest method, but has some drawbacks.

The first drawback is that a client app can only update its tags when the app is active. For example, if a user has two devices that register tags related to sport teams, when the first device registers for an additional tag (for example, Seahawks), the second device will not receive the notifications about the Seahawks until the app on the second device is executed a second time. More generally, when tags are affected by multiple devices, managing tags from the backend is a desirable option.

The second drawback of registration management from the client app is that, since apps can be hacked, securing the registration to specific tags requires extra care, as explained in the section “Tag-level security.”

Registration Management from the App Back-end

Managing registrations from the backend requires writing additional code. The app from the device must provide the updated PNS handle to the backend every time the app starts (along with tags and templates), and the backend must update this handle on Service Bus. The following picture illustrates this design.

The advantages of managing registrations from the backend are the ability to modify tags to registrations even when the corresponding app on the device is inactive, and to authenticate the client app before adding a tag to its registration.

From your app backend, you can perform basic CRUDS operations on registrations. For example:

var hub = NotificationHubClient.CreateClientFromConnectionString("{connectionString}", "hubName");
            
// create a registration description object of the correct type, e.g.
var reg = new WindowsRegistrationDescription(channelUri, tags);

// Create
await hub.CreateRegistrationAsync(reg);

// Get by id
var r = await hub.GetRegistrationAsync<RegistrationDescription>("id");

// update
r.Tags.Add("myTag");

// update on hub
await hub.UpdateRegistrationAsync(r);

// delete
await hub.DeleteRegistrationAsync(r);

You can also use Node or the REST APIs.

Additional Resources

The following scenario tutorials provide step-by-step guidance on registering from your app back-end:

• Use tags to send notifications to authenticated users

• Use templates to send cross-platform notifications to authenticated users