Azure Notification Hubs SDK for iOS v3.0.0-preview3

This is the third and final preview of the Azure Notification Hubs SDK for Apple, now with not only support for iOS, but also macOS and Mac Catalyst. Just as AppCenter Push supported these platforms, Azure Notification Hubs will also support these going forward. In addition to the platform support, we also now support the XCFramework bundle type.

We now have two sample apps showing off the same functionality across platform and language:

• NH Sample App for iOS/Mac Catalyst Objective-C Swift
• NH Sample App for macOS 10.9+ Objective-C Swift

There are a lot of changes, so let's dig in.

Initialization

Based upon feedback, we have changed initialization of the MSNotificationHub singleton class from initWithConnectionString to startWithConnectionString, which is a better name as it starts the whole installation process behind the scenes.

// Import the framework
#import <WindowsAzureMessaging/WindowsAzureMessaging.h>

// Get the Hub Name and Access Policy connection string
NSString *connectionString = @"<connection-string>";
NSString *hubName = @"<hub-name>";

[MSNotificationHub startWithConnectionString:connectionString hubName:hubName];

In Swift, we made some improvements to use the NS_SWIFT_NAME macro renaming startWithConnectionString to just start:

// Import the framework
import WindowsAzureMessaging

// Get the Hub Name and Access Policy connection string
let connectionString = "<connection-string>"
let hubName = "<hub-name>"

MSNotificationHub.start(connectionString: connectionString!, hubName: hubName!)

Intercepting Remote Notifications

By default, the Azure Notification Hubs SDK will swizzle methods to hook into the UIApplicationDelegate or NSApplicationDelegate methods, however, this can be disabled by setting the NHAppDelegateForwarderEnabled to false in your application pList file. To intercept messages, you must implement the MSNotificationHubDelegate protocol, which once again based upon being cross platform, has now been changed, removing the completionHandler, as it is not applicable cross platform, such as on macOS 10.9+.

// Import the framework
#import <WindowsAzureMessaging/WindowsAzureMessaging.h>

// Support the protocol
@interface AppDelegate () <MSNotificationHubDelegate>

@end

// Get the Hub Name and Access Policy connection string
NSString *connectionString = @"<connection-string>";
NSString *hubName = @"<hub-name>";

// Set the delegate and start the SDK
[MSNotificationHub setDelegate:self];
[MSNotificationHub startWithConnectionString:connectionString hubName:hubName];

// Implement the delegate method
- (void)notificationHub:(MSNotificationHub *)notificationHub didReceivePushNotification:(MSNotificationHubMessage *)notification {
    NSLog(@"Received notification: %@: %@", notification.title, notification.body);
}

The same can also be applied to Swift:

// Import the framework
import WindowsAzureMessaging

// Add support for the delegate
class AppDelegate: UIResponder, UIApplicationDelegate, MSNotificationHubDelegate

// Get the Hub Name and Access Policy connection string
let connectionString = "<connection-string>"
let hubName = "<hub-name>"

MSNotificationHub.setDelegate(self)
MSNotificationHub.start(connectionString: connectionString!, hubName: hubName!)

func notificationHub(_ notificationHub: MSNotificationHub!, didReceivePushNotification notification: MSNotificationHubMessage!) {
    NSLog("Received notification: %@; %@", notification.title ?? "<nil>", notification.body)
}

In addition to supporting the UIApplicationDelegate or NSApplicationDelegate protocols, the SDK now also support the newer UserNotifications Framework. The automatic swizzling can be disabled for these methods by setting the NHUserNotificationCenterDelegateForwarderEnabled to false in your application pList.

Handle Installation Lifecycle

As the SDK automatically handles the installation logic, automatically saving it to the Azure backend, you can also intercept the success or failure of the call to the backend through the MSInstallationLifecycleDelegate protocol which has two methods, didSaveInstallation for successful saves to the backend, and didFailToSaveInstallation for any failures. Should any call to the backend fail, you can invoke the call manually to the backend via the MSNotificationHub willSaveInstallation method.

@interface AppDelegate () <MSInstallationLifecycleDelegate>

@end

// Set the delegate
[MSNotificationHub setLifecycleDelegate:self];

// Handle successes
- (void)notificationHub:(MSNotificationHub *)notificationHub didSaveInstallation:(MSInstallation *)installation {
    NSLog(@"Successful save with Installation ID: %@", installation.installationId);
}

// Handle failure
- (void)notificationHub:(MSNotificationHub *)notificationHub
    didFailToSaveInstallation:(MSInstallation *)installation
                    withError:(NSError *)error {
    // Check error
    // Try to save again
    [MSNotificationHub willSaveInstallation];
}

In Swift, we can do the same via the following code:

class AppDelegate: MSInstallationLifecycleDelegate {

// Set the delegate
MSNotificationHub.setLifecycleDelegate(self)

// Handle success
func notificationHub(_ notificationHub: MSNotificationHub!, didSave installation: MSInstallation!) {
        
}

// Handle failure
func notificationHub(_ notificationHub: MSNotificationHub!, didFailToSave installation: MSInstallation!, withError error: Error!) {
    // Call the backend again
    MSNotificationHub.willSaveInstallation()
}

Installation Enrichment

By default, the SDK will update the installation on the device any time you change its properties such as adding a tag or adding an installation template. Before the installation is sent to the backend, you can intercept this installation to modify anything before it goes to the backend, for example, if you wish to add or modify tags. This is implemented in the MSInstallationEnrichmentDelegate protocol with a single method of willEnrichInstallation.

@interface AppDelegate () <MSInstallationEnrichmentDelegate>

@end

// Set the delegate
[MSNotificationHub setEnrichmentDelegate:self];

// Handle the enrichment
- (void)notificationHub:(MSNotificationHub *)notificationHub willEnrichInstallation:(MSInstallation *)installation {
    // Add another tag
    [installation addTag:@"customTag"];
}

And is supported in Swift as well:

class AppDelegate: MSInstallationEnrichmentDelegate {

// Set the delegate
MSNotificationHub.setEnrichmentDelegate(self)

// Handle the enrichment
func notificationHub(_ notificationHub: MSNotificationHub!, willEnrichInstallation installation: MSInstallation!) {
    installation.addTag("customTag")
}

Saving Installations to Your Own Backend

By default, the Azure Notification Hubs SDK will save the installation to our backend. If, however, you wish to skip our backend and store it on your backend, we support that through the MSInstallationManagementDelegate protocol. This has a method to save the installation willUpsertInstallation, passing in the installation, and then a completion handler is called with either an error if unsuccessful, or nil if successful.

@interface AppDelegate () <MSInstallationManagementDelegate>

@end

// Set the delegate
[MSNotificationHub setManagementDelegate:self];

// Save to your own backend
- (void)notificationHub:(MSNotificationHub *)notificationHub
    willUpsertInstallation:(MSInstallation *)installation
         completionHandler:(void (^)(NSError *_Nullable))completionHandler {
    // Save to your own backend
    // Call the completion handler with no error if successful
    completionHandler(nil);
}

This is also supported in Swift via the following:

class AppDelegate: MSInstallationManagementDelegate {

// Set the delegate
MSNotificationHub.setManagementDelegate(self)

func notificationHub(_ notificationHub: MSNotificationHub!, willUpsertInstallation installation: MSInstallation!, withCompletionHandler completionHandler: @escaping (NSError?) -> Void) {
    // Save to your own backend
    // Call the completion handler with no error if successful
    completionHandler(nil);
}

Breaking Changes

There were a number of breaking changes including:

• Rename initWithConnectionString on MSNotificationHub to startWithConnectionString or just start in Swift
• The MSNotificationHubDelegate protocol didReceivePushNotification removed the completionHandler callback and is handled automatically
• Instance methods on the MSNotificationHub class were removed in favor of the singleton methods.

Give Feedback

As always, we love to hear from you on how you're using the SDK, so please do give us feedback!

Azure Notification Hubs SDK for iOS v3.0.0-preview2

The Azure Notification Hubs SDK for iOS 3.0.0-preview2 is the second preview for the new 3.0.0 SDK. This SDK contains a new API to help developers familiar with AppCenter Push migrate their apps the underlying technology, Azure Notification Hubs. This build is available here via the WindowsAzureMessaging.framework.zip file or the AzureNotificationHubs-iOS CocoaPod. This builds upon the 3.0.0-preview1 release which adds support for Installation Templates.

To create an installation template, you can use the following API in Objective-C:

// Create template
MSInstallationTemplate *template = [MSInstallationTemplate new];

// Set some properties
template.body = @"This is a template body";
[template addTag:@"tag1"];
[template setHeaderValue:@"custom-header-value" forKey:"x-custom-header"];

// Add it to the installation
[MSNotificationHub setTemplate:template forKey:@"template1"];

Using Swift, your code would look as follows:

// Create template
let template = MSInstallationTemplate()

// Set some properties
template.body = "This is a template Body"
template.addTag("tag1");
template.setHeader("custom-header-value", forKey: "x-custom-header");

// Add it to the installation
MSNotificationHub.setTemplate(template, forKey: "template1");

Azure Notification Hubs SDK for iOS v3.0.0-preview1

The Azure Notification Hubs SDK for iOS 3.0.0-preview1 is the first preview for the new 3.0.0 SDK. This SDK contains a new API to help developers familiar with AppCenter Push migrate their apps the underlying technology, Azure Notification Hubs.

Getting started with the SDK once manually installed via the WindowsAzureMessaging.framework.zip file or using the AzureNotificationHubs-iOS CocoaPod, you can get started with the following code where you initialize the MSNotificationHub with a listen only access policy such as DefaultListenSharedAccessSignature, and the hub name. In addition, in order to receive push notifications, you must implement the MSNotificationHubDelegate protocol.

This can be done with Objective-C such as the following:

#import <WindowsAzureMessaging/WindowsAzureMessaging.h>

// Later in the AppDelegate
static NSString *const kConnectionString = @""; // A listen only access policy connection string
static NSString *const kHubName = @""; // The Azure Notification Hub Name

// Initialize the Notification Hub
[MSNotificationHub setDelegate:this];
[MSNotificationHub initWithConnectionString:kConnectionString hubName:kHubName];

// Listen for push notifications from APNS
- (void)notificationHub:(MSNotificationHub *)notificationHub didReceivePushNotification:(MSNotificationHubMessage *)message fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    NSLog(@"Received notification: %@: %@", notification.title, notification.body);

    // Set completion handler to no data
    completionHandler(UIBackgroundFetchResultNoData);
}

And Swift as the following code once importing the SDK and creating the Bridging Header via importing Objective-C code into Swift.

import WindowsAzureMessaging

static let connectionString = "{Connection String}"
static let hubName = "{Hub Name}"

MSNotificationHub.setDelegate(self)
MSNotificationHub.initWithConnectionString(connectionString, hubName: hubName)

func notificationHub(_ notificationHub: MSNotificationHub!, didReceivePushNotification notification: MSNotificationHubMessage!, fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    // Log the data
    NSLog("Received notification: %@; %@", notification.title ?? "<nil>", notification.body)

    // Set completion handler to no-data
    completionHandler(.noData)
}

Registering your device is handled automatically behind the scenes using swizzling. You can enhance the targeting experience for your device such as using tags. For example, you can add tags for your app using the following API with Objective-C.

// Add a single tag
[MSNotificationHub addTag:@"tag1"];

// Add multiple tags
[MSNotificationHub addTags:@[@"tag2", @"tag3", "tag4"]];

// Remove a tag
[MSNotificationHub removeTag:@"tag1"];

// Remove multiple tags
[MSNotificationHub addTags:@[@"tag2", @"tag3", "tag4"]];

// Get all tags
NSSet *tags = [MSNotificationHub getTags];

The same can be done using Swift with the following code.

// Add a tag
MSNotificationHub.addTag("iOS")

// Add multiple tags
MSNotificationHub addTags(["tag2", "tag3", "tag4"])

// Remove a tag
MSNotificationHub.removeTag("iOS");

// Remove multiple tags
MSNotificationHub.addTag(["tag2", "tag3", "tag4"])

// Get all tags
var tags = MSNotificationHub.getTags();

2.0.4

• Fixed issue with registrations on iOS 13

2.0.3

CocoaPods release