App Center Push

App Center Push enables you to send push notifications to users of your app from the App Center portal.

Prerequisite - Enable Apple Push Notifications service (APNs) for your app

Configure Apple Push Notifications service (APNs) for your app from your Apple developer account and App Center portal before adding App Center Push to your app.

Enable push notifications on your application

In Xcode's project editor, choose your target and click Capabilities. In the Push Notifications section, click the switch to turn it from OFF to ON.

enable-push-capability

Set up APNs

Log in to the App Center portal, select your application, click on the Push button from the left menu then click Next to reveal the push notification settings UI:

app-center-push-settings

  • On the bottom of the page, select Sandbox for initial development or Production for production version of your application.

  • Collect the following information:

    1. Prefix and ID

      • Go to your Apple developer account and select your application from the App ID list in Identifiers.

      • Copy the Prefix value from this window and paste it to the App Center push settings.

      • Do the same with the ID value.

      apple-dev-center-app-id

    2. Key ID

      • In your Apple developer account create a new key in Certificates, Identifiers & Profiles/Keys.

      • Make sure to check the APNs checkbox.

      • Fill in the key name

      • Press Continue then Confirm.

      apple-dev-center-new-auth-key

      • On the next screen, copy the Key ID value and paste it to the App Center push settings.

      • Download the key file.

      apple-dev-center-confirm-auth-key

    3. Push Token

      • Open your key file with a text editor and copy the authentication token it contains.

      auth-key-file

      • On the App Center push settings, paste this token to the Push Token field then click Done to complete this configuration.

For more information, refer to the Apple documentation.

Add App Center Push to your app

1. Add the App Center Push module

The App Center SDK is designed with a modular approach – you only need to integrate the services that you're interested in.

Integration via Cocoapods

If you are integrating App Center into your app via Cocoapods, add the following dependency to your podfile and run pod install.

pod 'AppCenter/Push'

Integration by copying the binaries into your project

If you wish to manually integrate the module, follow this documentation link.

2. Start App Center Push

In order to use App Center, you need to opt in to the service(s) that you want to use, meaning by default no services are started and you will have to explicitly call each of them when starting the SDK.

2.1 Add the import for App Center Push

Open your AppDelegate.m file in Objective-C or AppDelegate.swift file in Swift and add the following import statements:

@import AppCenter;
@import AppCenterPush;
import AppCenter
import AppCenterPush

2.2 Add the start:withServices: method

Add MSPush to your start:withServices: method to start App Center Push together with the other services that you want to use in your app.

Insert the following line to start the SDK in your app's AppDelegate.m class in Objective-C or AppDelegate.swift class in Swift in the applicationDidFinishLaunching method.

[MSAppCenter start:@"{Your App Secret}" withServices:@[[MSPush class]]];
MSAppCenter.start("{Your App Secret}", withServices: [MSPush.self])

Make sure you have replaced {Your App Secret} in the code sample above with your App Secret. Please also check out the Get started section if you haven't configured the SDK in your application.

2.3 Add internet capabilities for sandboxed apps

If your app is using the App Sandbox, you have to set the capability to allow incoming (Server) and outgoing (Client) connections to allow the app to have access to the internet. Xcode 9 enables the App Sandbox by default but the capabilities for incoming and outgoing connections need to be set explicitly.

Select your project in the project navigator, select the Capabilities tab and if your app is using the sandbox, enable incoming and outgoing connections.

Intercept push notifications

You can set up a delegate to be notified whenever a push notification is received while the application is active (currently frontmost) or a notification in Notification Center has been clicked by the user.

By default, App Center Push does not generate notifications when the push is received while the application is active, you can use the delegate to customize the push experience when received while the application is active or do a specific action when the application is being active by clicking on the notification from Notification Center when received while the application is inactive. App Center Push will not generate any notifications if the push is received while the application is not running.

You need to register the delegate before starting App Center as shown in the following example:

[MSPush setDelegate:self];
[MSAppCenter start:@"{Your App Secret}" withServices:@[[MSPush class]]];
MSPush.setDelegate(self)
MSAppCenter.start("{Your App Secret}", withServices: [MSPush.self])

Here is an example of the delegate implementation that displays an alert dialog when the message is received by App Center Push:

- (void)push:(MSPush *)push didReceivePushNotification:(MSPushNotification *)pushNotification {
  NSString *title = pushNotification.title ?: @"";
  NSString *message = pushNotification.message;
  NSMutableString *customData = nil;
  for (NSString *key in pushNotification.customData) {
    ([customData length] == 0) ? customData = [NSMutableString new] : [customData appendString:@", "];
    [customData appendFormat:@"%@: %@", key, [pushNotification.customData objectForKey:key]];
  }
  message = [NSString stringWithFormat:@"%@%@%@", (message ? message : @""), (message && customData ? @"\n" : @""),
                                       (customData ? customData : @"")];
  NSAlert *alert = [[NSAlert alloc] init];
  [alert setMessageText:title];
  [alert setInformativeText:message];
  [alert addButtonWithTitle:@"OK"];
  [alert runModal];
}
func push(_ push: MSPush!, didReceive pushNotification: MSPushNotification!) {
  let title: String = pushNotification.title ?? ""
  var message: String = pushNotification.message ?? ""
  var customData: String = ""
  for item in pushNotification.customData {
    customData =  ((customData.isEmpty) ? "" : "\(customData), ") + "\(item.key): \(item.value)"
  }
  message =  message + ((customData.isEmpty) ? "" : "\n\(customData)")
  let alert: NSAlert = NSAlert()
  alert.messageText = title
  alert.informativeText = message
  alert.addButton(withTitle: "OK")
  alert.runModal()
}

Enable or disable App Center Push at runtime

You can enable and disable App Center Push at runtime. If you disable it, the SDK will stop updating the device token used to push but the existing one will continue working. In other words, disabling the App Center Push in the SDK will NOT stop your application from receiving push notifications.

[MSPush setEnabled:NO];
MSPush.setEnabled(false)

To enable App Center Push again, use the same API but pass YES/true as a parameter.

[MSPush setEnabled:YES];
MSPush.setEnabled(true)

Check if App Center Push is enabled

You can also check if App Center Push is enabled or not:

BOOL enabled = [MSPush isEnabled];
var enabled = MSPush.isEnabled()

Disable automatic forwarding of application delegate's methods to App Center services

App Center uses swizzling to automatically forward your application delegate's methods to App Center services to improve SDK integration. There is a possibility of conflicts with other third party libraries or the application delegate itself. In this case, you might want to disable the App Center application delegate forwarding for all App Center services by following the steps below:

  1. Open your Info.plist file.
  2. Add AppCenterAppDelegateForwarderEnabled key and set the value to 0. This will disable application delegate forwarding for all App Center services.
  3. Implement the callbacks to register push notifications

    Implement the application:didRegisterForRemoteNotificationsWithDeviceToken: callback and the application:didFailToRegisterForRemoteNotificationsWithError: callback in your AppDelegate to register for Push notifications.

    - (void)application:(NSApplication *)application
        didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    
      // Pass the device token to MSPush.
      [MSPush didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
    }
    
    - (void)application:(NSApplication *)application
        didFailToRegisterForRemoteNotificationsWithError:(nonnull NSError *)error {
    
      // Pass the error to MSPush.
      [MSPush didFailToRegisterForRemoteNotificationsWithError:error];
    }
    
    func application(_ application: NSApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    
      // Pass the device token to MSPush.
      MSPush.didRegisterForRemoteNotifications(withDeviceToken: deviceToken)
    }
    
    func application(_ application: NSApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    
      // Pass the error to MSPush.
      MSPush.didFailToRegisterForRemoteNotificationsWithError(error)
    }
    
  4. Implement the callback to receive push notifications

    Implement the application:didReceiveRemoteNotification: callback to forward push notifications to the Push service.

    - (void)application:(NSApplication *)application
        didReceiveRemoteNotification:(NSDictionary *)userInfo {
      [MSPush didReceiveRemoteNotification:userInfo];
    }
    
    func application(_ application: NSApplication, didReceiveRemoteNotification userInfo: [String : Any]) {
      MSPush.didReceiveRemoteNotification(userInfo)
    }