Swiftpack.co - Package - Azure/azure-notificationhubs-ios

framework-docs analyze-test

Microsoft Azure Notification Hubs SDK for Apple

Microsoft Azure Notification Hubs provide a multiplatform, scaled-out push infrastructure that enables you to send mobile push notifications from any backend (in the cloud or on-premises) to any mobile platform. To learn more, visit our Developer Center.

The Azure Notification Hubs SDK for Apple provides capabilities for registering your device and receive push notifications on macOS and iOS including platforms including tvOS, watchOS and Mac Catalyst.

Getting Started

The Azure Notification Hubs can be added to your app via Cocoapods, Carthage, Swift Package Manager, or by manually adding the binaries to your project. We have a number of sample applications available written in both Swift and Objective-C to help you get started for both iOS with Mac Catalyst support, and a macOS sample, and SwiftUI coming soon.

This introduces a new API as of version 3.0, and the usage of SBNotificationHub with registrations is still supported, but discouraged as we have the new MSNotificationHub which uses the Installation API and modern Apple APIs.

  1. NH Sample App for iOS/Mac Catalyst (Swift | Objective-C)
  2. NH Sample App for macOS (Swift | Objective-C)
  3. NH Sample App for SwiftUI (iOS | macOS)
  4. NH Sample Legacy App using Legacy APIs (Swift | Objective-C)

Integration with Cocoapods

Add the following into your podfile to pull in the Azure Notification Hubs SDK:

pod 'AzureNotificationHubs-iOS'

Run pod install to install the pod and then open your project workspace in Xcode.

Integration with Carthage

Below are the steps on how to integrate the Azure Notification Huds SDK in your Xcode project using Carthage version 0.30 or higher. Add the following to your Cartfile to include GitHub repository.

# Gets the latest release
github "Azure/azure-notificationhubs-ios"

You can also specify a specific version of the Azure Notification Hubs SDK such as 3.1.1s.

# Get version in the format of X.X.X such as 3.1.1
github "Azure/azure-notificationhubs-ios" ~> 3.1.1

Once you have this, run carthage update. This will fetch the SDK and put it into the Carthage/Checkouts folder. Open Xcode and drag the WindowsAzureMessaging.framework from the Carthage/Builds/iOS for iOS or Carthage/Builds/macOS for macOS. Ensure the app target is checked during the import.

Integration via Swift Package Manager

The Azure Notification Hubs SDK also supports the Swift Package Manager. To integrate, use the following steps:

  1. From the Xcode menu click File > Swift Packages > Add Package Dependency.
  2. In the dialog, enter the repository URL: http://github.com/Azure/azure-notificationhubs-ios.git
  3. In the Version, select Up to Next Major and take the default option.
  4. Choose WindowsAzureMessaging in the Package Product column.

Integration via copying binaries

The Azure Notification Hubs SDK can also be added manually by downloading the release from GitHub on the Azure Notification Hubs SDK Releases.

The SDK supports the use of XCframework. If you want to integrate XCframeworks into your project, download the WindowsAzureMessaging-SDK-Apple-XCFramework.zip from the releases page and unzip it. Resulting folder contents are not platform-specific, instead it contains the XCframework.

Unzip the file and you will see a folder called WindowsAzureMessaging-SDK-Apple that contains the framework files each platform folder. Copy the framework to a desired location and then add to Xcode. Ensure the app target is checked during the import.

Initializing the SDK

To get started with the SDK, you need to configure your Azure Notification Hub with your Apple credentials. To integrate the SDK, you will need the name of the hub as well as a connection string from your Access Policies. Note that you only need the "Listen" permission to intercept push notifications.

You can then import the headers for Swift:

import WindowsAzureMessaging

And Objective-C as well:

#import <WindowsAzureMessaging/WindowsAzureMessaging.h>

Then we can initialize the SDK with our hub name and connection string. This will automatically register the device using the Installation API with your device token.

Using Swift, we can use the start method, which then starts the installation and device registration process for push notifications.

Swift:

let connectionString = "<connection-string>"
let hubName = "<hub-name>"

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

With Objective-C, it is largely the same with calling the startWithConnectionString method:

Objective-C:

NSString *connectionString = @"<connection-string>";
NSString *hubName = @"<hub-name>";

[MSNotificationHub startWithConnectionString:connectionString hubName:hubName];

Intercepting Push Notifications

You can set up a delegate to be notified whenever a push notification is received in foreground or a background push notification has been tapped by the user. To get started with intercepting push notifications, implement the MSNotificationHubDelegate, and use the MSNotificationHub.setDelegate method to set the delegate implementation.

Swift:

class SetupViewController: MSNotificationHubDelegate // And other imports

// Set up the delegate
MSNotificationHub.setDelegate(self)

// Implement the method
func notificationHub(_ notificationHub: MSNotificationHub!, didReceivePushNotification notification: MSNotificationHubMessage!) {

    let title = notification.title ?? ""
    let body = notification.body ?? ""

    if (UIApplication.shared.applicationState == .background) {
        NSLog("Notification received in background: title:\"\(title)\" body:\"\(body)\"")
    } else {
        let alertController = UIAlertController(title: title, message: body, preferredStyle: .alert)
        alertController.addAction(UIAlertAction(title: "OK", style: .cancel))

        self.present(alertController, animated: true)
    }
}

Objective-C:

@interface SetupViewController <MSNotificationHubDelegate /* Other protocols */>

// Set up the delegate
[MSNotificationHub setDelegate:self];

// Implement the method
- (void)notificationHub:(MSNotificationHub *)notificationHub didReceivePushNotification:(MSNotificationHubMessage *)notification {
    NSString *title = notification.title ?: @"";
    NSString *body = notification.body ?: @"";

    if ([[UIApplication sharedApplication] applicationState] == UIApplicationStateBackground) {
        NSLog(@"Notification received in the background: title: %@ body: %@", title, body);
    } else {
        UIAlertController *alertController = [UIAlertController alertControllerWithTitle:notification.title
                        message:notification.body
                 preferredStyle:UIAlertControllerStyleAlert];
        [alertController addAction:[UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleCancel handler:nil]];

        [self presentViewController:alertController animated:YES completion:nil];
    }
}

Tag Management

One of the ways to target a device or set of devices is through the use of tags, where you can target a specific tag, or a tag expression. The Azure Notification Hub SDK for Apple handles this through top level methods that allow you to add, clear, remove and get all tags for the current installation. In this example, we can add some recommended tags such as the app language preference, and device country code.

Swift:

// Get language and country code for common tag values
let language = Bundle.main.preferredLocalizations.first!
let countryCode = NSLocale.current.regionCode!

// Create tags with type_value format
let languageTag = "language_" + language
let countryCodeTag = "country_" + countryCode

MSNotificationHub.addTags([languageTag, countryCodeTag])

Objective-C:

// Get language and country code for common tag values
NSString *language = [[[NSBundle mainBundle] preferredLocalizations] objectAtIndex:0];
NSString *countryCode = [[NSLocale currentLocale] countryCode];

// Create tags with type_value format
NSString *languageTag = [NSString stringWithFormat:@"language_%@", language];
NSString *countryCodeTag = [NSString stringWithFormat:@"country_%@", countryCode];

[MSNotificationHub addTags:@[languageTag, countryCodeTag]];

Template Management

With Azure Notification Hub Templates, you can enable a client application to specify the exact format of the notifications it wants to receive. This is useful when you want to create a more personalized notification, with string replacement to fill the values. The Installation API allows multiple templates for each installation which gives you greater power to target your users with rich messages.

For example, we can create a template with a body, some headers, and some tags.

Swift:

// Get language and country code for common tag values
let language = Bundle.main.preferredLocalizations.first!
let countryCode = NSLocale.current.regionCode!

// Create tags with type_value format
let languageTag = "language_" + language
let countryCodeTag = "country_" + countryCode

let body = "{\"aps\": {\"alert\": \"$(message)\"}}"
let template = MSInstallationTemplate()
template.body = body
template.addTags([languageTag, countryCodeTag])

MSNotificationHub.setTemplate(template, forKey: "template1")

Objective-C:

NSString *language = [[[NSBundle mainBundle] preferredLocalizations] objectAtIndex:0];
NSString *countryCode = [[NSLocale currentLocale] countryCode];

// Create tags with type_value format
NSString *languageTag = [NSString stringWithFormat:@"language_%@", language];
NSString *countryCodeTag = [NSString stringWithFormat:@"country_%@", countryCode];

NSString *body = @"{\"aps\": {\"alert\": \"$(message)\"}}";

MSInstallationTemplate *template = [MSInstallationTemplate new];
template.body = body;

[template addTags:@[languageTag, countryCodeTag]];

[MSNotificationHub setTemplate:template forKey:@"template1"];

Push to User Management

The SDK supports the ability to associate a user with an installation. This allows you to be able to target all devices associated with a particular User ID. The user's identity set through the SDK can be whatever the developer wants it to be: the user's name, email address, phone number, or some other unique identifier. This is supported through the MSNotificationHub and the setUserId method.

Swift:

let userId = "iosUser123"
MSNotificationHub.setUserId(userId);

Objective-C:

NSString *userId = @"iosUser123";
[MSNotificationHub setUserId:userId];

To target a particular user on the backend, you can specify a tag such as $UserId:{VALUE} where VALUE is the user name you have specified, just as you can target an installation using the $InstallationId:{VALUE} tag.

Intercepting Installation Management

The SDK will handle saving the installation for you, however, we provide hooks where you can intercept both the successful installation or any failure through the MSInstallationLifecycleDelegate. This has two methods, didSaveInstallation for successful saves, and didFailToSaveInstallation for any failures. We can implement this to have our own logging for example.

Swift:

// Set the delegate
MSNotificationHub.setLifecycleDelegate(self)

// Handle success
func notificationHub(_ notificationHub: MSNotificationHub!, didSave installation: MSInstallation!) {
    let installationId = installation.installationId;
    NSLog("Successful save with Installation ID: \"\(installationId)\"")
}

// Handle failure
func notificationHub(_ notificationHub: MSNotificationHub!, didFailToSave installation: MSInstallation!, withError error: Error!) {
    NSLog("Failed to save installation")
}

Objective-C:

// 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 {
    NSLog(@"Failed to save installation with error %@", [error localizedDescription]);
}

Enriching Installations

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.

Swift:

// Set the delegate
MSNotificationHub.setEnrichmentDelegate(self)

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

Objective-C:

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

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

Saving Installations to a Custom Backend

The Azure Notification Hubs SDK will save the installation to our backend by default. 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. To set the delegate, instead of specifying the connection string and hub name, you specify the installation manager with startWithInstallationManagement

Swift:

// Set the delegate
MSNotificationHub.startWithInstallationManagement(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);
}

Objective-C:

// Set the delegate
[MSNotificationHub startWithInstallationManagement: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);
}

Disabling Automatic Swizzling

By default, the SDK will swizzle methods to automatically intercept calls to UIApplicationDelegate/NSApplicationDelegate for calls to registering and intercepting push notifications, as well as UNUserNotificationCenterDelegate methods. Note this is only available for iOS, watchOS, and Mac Catalyst. This is not supported on macOS and tvOS.

Disabling UIApplicationDelegate/NSApplicationDelegate

  1. Open the project's Info.plist

  2. Add the NHAppDelegateForwarderEnabled key and set the value to 0. This disables the UIApplicationDelegate/NSApplicationDelegate auto-forwarding to MSNotificaitonHub.

  3. Implement the MSApplicationDelegate/NSApplicationDelegate methods for push notifications.

    Implement the application:didRegisterForRemoteNotificationsWithDeviceToken: callback and the application:didFailToRegisterForRemoteNotificationsWithError: callback in your AppDelegate to register for Push notifications. In the code below, if on macOS, not Mac Catalyst, replace UIApplication with NSApplication.

    Swift:

    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    
        // Pass the device token to MSNotificationHub
        MSNotificationHub.didRegisterForRemoteNotifications(withDeviceToken: deviceToken)
    }
    
    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    
        // Pass the error to MSNotificationHub
        MSNotificationHub.didFailToRegisterForRemoteNotificationsWithError(error)
    }
    

    Objective-C:

    - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
        // Pass the device token to MSNotificationHub
        [MSNotificationHub didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
    }
    
    - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
        // Pass the error to MSNotificationHub
        [MSNotificationHub didFailToRegisterForRemoteNotificationsWithError:error];
    }
    
  4. Implement the callback to receive push notifications

    Implement the application:didReceiveRemoteNotification:fetchCompletionHandler callback to forward push notifications to MSNotificationHub In the code below, if on macOS, not Mac Catalyst, replace UIApplication with NSApplication.

    Swift:

    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    
        // Forward to MSNotificationHub
        MSNotificationHub.didReceiveRemoteNotification(userInfo)
    
        // Complete handling the notification
        completionHandler(.noData)
    }
    

    Objective-C:

    - (void)application:(UIApplication *)application
        didReceiveRemoteNotification:(NSDictionary *)userInfo
              fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    
        // Forward to MSNotificationHub
        [MSNotificationHub didReceiveRemoteNotification:userInfo];
    
        // Complete handling the notification
        completionHandler(UIBackgroundFetchResultNoData);
    }
    

Disabling UNUserNotificationCenterDelegate

  1. Open the project's Info.plist

  2. Add the NHUserNotificationCenterDelegateForwarderEnabled key and set the value to 0. This disables the UNUserNotificationCenterDelegate auto-forwarding to MSNotificaitonHub.

  3. Implement UNUserNotificationCenterDelegate callbacks and pass the notification's payload to MSNotificationHub.

    Swift:

    @available(iOS 10.0, *)
    func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    
        //...
    
        // Pass the notification payload to MSNotificationHub
        MSNotificationHub.didReceiveRemoteNotification(notification.request.content.userInfo)
    
        // Complete handling the notification
        completionHandler([])
    }
    
    @available(iOS 10.0, *)
    func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    
        //...
    
        // Pass the notification payload to MSNotificationHub
        MSNotificationHub.didReceiveRemoteNotification(response.notification.request.content.userInfo)
    
        // Complete handling the notification
        completionHandler()
    }
    

    Objective-C:

    - (void)userNotificationCenter:(UNUserNotificationCenter *)center
          willPresentNotification:(UNNotification *)notification
            withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
            API_AVAILABLE(ios(10.0), tvos(10.0), watchos(3.0)) {
    
        //...
    
        // Pass the notification payload to MSNotificationHub
        [MSNotificationHub didReceiveRemoteNotification:notification.request.content.userInfo];
    
        // Complete handling the notification
        completionHandler(UNNotificationPresentationOptionNone);
    }
    
    - (void)userNotificationCenter:(UNUserNotificationCenter *)center
       didReceiveNotificationResponse:(UNNotificationResponse *)response
                withCompletionHandler:(void (^)(void))completionHandler API_AVAILABLE(ios(10.0), tvos(10.0), watchos(3.0)) {
    
        //...
        [MSNotificationHub didReceiveRemoteNotification:response.notification.request.content.userInfo];
    
        // Complete handling the notification
        completionHandler();
    }
    

Useful Resources

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

All Objective-C files follow LLVM coding style (with a few exceptions) and are formatted accordingly. To format your changes, make sure you have the clang-format tool. It can be installed with Homebrew using the command brew install clang-format. Once you have installed clang-format, run ./clang-format-changed-files.sh from the repository root - this will format all files that have changes against the remote main branch (it will also perform a git fetch).

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Github

link
Stars: 12

Dependencies

Used By

Total: 0

Releases

Azure Notification Hubs SDK for Apple 3.1.1 - 2020-09-02 22:58:45

The Azure Notification Hubs SDK for Apple version 3.1.1 has been released with the following:

  • Update the x-ms-version header to 2020-06

Azure Notification Hubs SDK for Apple 3.1.0 - 2020-08-17 22:35:59

This release adds the Push to User functionality to the Azure Notification Hubs SDK for Apple.

Push to User

The SDK supports the ability to associate a user with an installation. This allows you to be able to target all devices associated with a particular User ID. The user's identity set through the SDK can be whatever the developer wants it to be: the user's name, email address, phone number, or some other unique identifier. This is supported through the MSNotificationHub and the setUserId method.

Swift:

let userId = "iosUser123"
MSNotificationHub.setUserId(userId);

Objective-C:

NSString *userId = @"iosUser123";
[MSNotificationHub setUserId:userId];
To target a particular user on the backend, you can specify a tag such as $UserId:{VALUE} where VALUE is the user name you have specified, just as you can target an installation using the $InstallationId:{VALUE} tag.

Azure Notification Hubs SDK for Apple 3.0.2 - 2020-08-11 02:13:49

Minor release which includes the following:

Bug Fixes:

  • #93

Azure Notification Hubs SDK for Apple - 2020-08-04 20:18:57

This is a minor release with the following fixes:

  • Add Jazzy SDK Documentation for iOS, tvOS and macOS
  • Ensure bitcode for release

Azure Notification Hubs SDK for Apple 3.0.0 - 2020-08-03 19:54:20

The Azure Notification Hubs SDK for Apple has finally been released. This introduces a new API through the MSNotificationHub class, which utilizes the Installation API instead of the legacy Registration API. This new API includes support for iOS, tvOS, macOS and Mac Catalyst. Note, the existing SBNotificationHub class is considered legacy and not recommended for new application usage.

Azure Notification Hubs SDK for Apple 3.0.0-preview4 - 2020-07-15 16:27:02

This is a minor patch release of the Azure Notification Hubs SDK for Apple containing some fixes which solve some bugs from symbol collisions when mixed with AppCenter frameworks.

Azure Notification Hubs SDK for iOS v3.0.0-preview3 - 2020-07-03 02:13:21

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:

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 - 2020-05-21 23:21:51

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 - 2020-05-14 15:32:59

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 - 2019-09-06 04:41:17

  • Fixed issue with registrations on iOS 13

2.0.3 - 2019-02-28 13:00:01

CocoaPods release