App Center Push

App Center Push enables you to send push notifications to your app users 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 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

      • On the App Center push settings page, upload your key file using the button labelled "Auth key file:" (you can also drag and drop the file onto it):

        auth-key-file

      • Click Done to complete this configuration.

For more information, refer to the Apple documentation.

[Optional] Enable silent notifications

Silent notifications give you a way to wake up your app so that it can refresh its data in the background (see Apple documentation). To enable silent notifications open Xcode's project editor, choose your target and click Capabilities. Turn on Background Modes and check the Remote notifications checkbox.

enable-silent-notifications

Note

If there are no user-visible updates that go along with the background update, you can leave the title and message fields empty to prevent showing any visible notifications.

Note

Silent notifications are the mechanism behind background app refresh, the user can open settings (General > Background App Refresh) and disable them. You can't depend on them always being available.

Add App Center Push to your app

Please follow the Get started section if you haven't set up and started the SDK in your application yet. The App Center SDK is designed with a modular approach – you can integrate only those services that you're interested in.

To add App Center Push to your app open a Terminal and navigate to the root of your Cordova project, then enter the following to add App Center Push to the app:

cordova plugin add cordova-plugin-appcenter-push

Intercept push notifications

You can set up a listener to be notified whenever a push notification is received in foreground or a background push notification has been tapped by the user. The listener may also be woken up when a notification is received in background if you have enabled silent notifications and if the payload of the notification contains the content-available flag set to true.

Note

If silent notifications are enabled and you push a notification with content-available: 1, then the listener may be triggered twice for the same notification: when the notification is received in background and when it is tapped.

By default, iOS does not generate notifications when the push is received in foreground, you can use the listener to customize the push experience when received in foreground or do a specific action when the application is launched by clicking on the push notification when received in background.

You need to register the listener when your app starts. A convenient place to do that is at app.onDeviceReady method of your `js/index.js:

var app = {

  onDeviceReady: function() {
    
    var onNotificationReceived = function(pushNotification) {
        var message = pushNotification.message;
        var title = pushNotification.title;

        if (message === null || message === undefined) {
            // Android messages received in the background don't include a message. On Android, that fact can be used to
            // check if the message was received in the background or foreground. For iOS the message is always present.
            title = 'Android background';
            message = '<empty>';
        }

        // Custom name/value pairs set in the App Center web portal are in customProperties
        if (pushNotification.customProperties && Object.keys(pushNotification.customProperties).length > 0) {
            message += '\nCustom properties:\n' + JSON.stringify(pushNotification.customProperties);
        }
        
        console.log(title, message);
    }

    AppCenter.Push.addEventListener('notificationReceived', onNotificationReceived);    
  
    // ...
    
  },  

};

app.initialize();

Custom data in your notifications

You can send optional custom data as part of the push payload. The data will be sent in the key-value format. This custom data can be intercepted in the app through Push SDK callback.

There are few reserved keywords that can be set via custom data.

Reserved keywords in iOS platform

  • badge: Add this key when you want to modify the badge of your app icon. If this key is not included, the badge is not changed. To remove the badge, set the value of this key to 0.
  • sound: Add this key when you want the to play a sound. The value of this key is the name of a sound file in your app's main bundle or in the Library/Sounds folder of your app’s data container. If the sound file cannot be found, or if you specify default for the value, the system plays the default alert sound.
  • content-available: Add this key with a value of 1 to configure a silent notification. When this key is present, the system wakes up your app in the background and delivers the notification to its app delegate. For information about configuring and handling silent notifications, see Configuring a Silent Notification.
  • mutable-content: Add this key with a value of 1 to enable media attachments. The application needs to support a service extension to download and handle the attachment content. For more information you can refer to Apple documentations.

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 Google registration identifier 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.

var enableSuccess = function() {
    console.log("push notifications enabled");
}

var disableSuccess = function() {
    console.log("push notifications disabled");
}

var error = function(error) {
    console.error(error);
}

AppCenter.Push.setEnabled(false, disableSuccess, error); // Disable push
AppCenter.Push.setEnabled(true, enableSuccess, error); // Re-enable it

The state is persisted in the device's storage across application launches.

Check if App Center Push is enabled

You can also check whether App Center Push is enabled:

var success = function(result) {
    console.log("push notifications " + (result) ? "enabled" : "disabled");
}

var error = function(error) {
    console.error(error);
}

AppCenter.Push.isEnabled(success, error);