Push Notifications

Sencha Web Application Manager allows an application developer to send push notifications to an application running in Sencha Web Application client. Three types of notifications are supported:

• An alert that is shown to the user and is actionable
• A badge that shows a string next to the application name
• A data string that is received by the application

Overview

The overall interaction between the various parties is as follows:

For example, this is how an email application could utilize push notifications inside of Sencha Web Application Manager:

1. The email application, running in Sencha Web Application Client, collects the application Id and current user email of the Sencha Web Application Manager user.
2. The application sends the information to a server that has credentials for the Sencha Web Application Manager public API.
3. When the user receives an email, the server prepares a payload.
   1. Alert for the new email
   2. Badge for the new unread email count
   3. Data for an internal application update
4. Using the public API, the server sends the payload with the other required information to the Sencha Web Application Manager server.
5. The Sencha Web Application Manager server forwards the payload to all devices belonging to that user.
6. The application on one of the devices has the email read by the user.
7. That application clears the badge on the device.
8. The new badge value is sent to the Sencha Web Application Manager server, clearing the badge on the other devices owned by the user.

Sencha Web Application Manager Administrator

Sencha Web Application Manager administrator modify push notification access via the API access section of the application’s info tab.

Appliction notifications

API level access to notifications. This includes local notifications, set application badges, and get notification settings.

Push notifications

This setting allows the client to receive push notifications from the server. If it is disabled, calls to the notification method of the push service in the public API will receive an error.

Push notification settings

This setting allows the client to opt in/out of notification alerts and badges. If Push notifications is disabled, this setting does nothing, as the client will never receive alerts and badges. If Push notifications is enabled and this setting is disabled, users will always receive alerts and badges.

Server

The currently supported method to push notifications to an application is through the public API. The server sends the following information:

• id - A number to track the response.
• auth - ‘push’
• method - ‘notification’
• auth - Your authentication token.
• bookmarkId - The application’s id, obtained by the application and Ext.spaceAppId.
• userEmail (optional) - The user’s email target, obtained by the application at the profile API.
• badge - The application badge.
• data - A string of data.
• alert - An alert to show containing the following properties.
• message - The alert message.
• icon (optional) - The alert icon. The alert will revert to the application icon if missing.
• tags (optional) - An array of strings that will be sent to the application with the alert.

Note: The body only needs at least one of alert, data, or badge.

The following post body is an example that shows an alert and sets the application’s badge value to 3.

 {  id: 1,  auth: ‘yourauthtoken’,  service: ‘push’,  method: ‘notification’,  params: {  bookmarkId: 1022,  userEmail: ’[email protected]',  alert: {  message: ‘You have a new message!’,  icon: ’http://icondomain.com/path/icon.png',  tags: [‘unread’,‘test’]  },  badge: ‘3’  } } 

Sencha Web Application Client Application Developer

Here are a few of the APIs available to developers created applications for Sencha Web Application Client. For a complete list, please visit our documentation.

Receiving Events

You can receive events for three different types of notifications: badge, data, and alert.

Application Notifications

The normal way to listen for notifications is using the Ext.space.Notification API.

Ext.space.Notification.onBadgeChange(function(badge) {
	// badge changed
});

Ext.space.Notification.onData(function(data) {
	// data received
});

Ext.space.Notification.onAlert(function(alert) {
	// alert received
});

The badge and data parameters are simple scalar values; the alert object contains:

• message (string)
• icon (string)
• tags (array)

Cross-Application Notifications

You can also receive events for notification that are sent to any installed application in the current organization. Normal applications will not find this useful, but it helps when creating things like administration dashboards.

Ext.space.Applications.onBadgeChange(function(appId, badge) {
	// badge changed
});

Ext.space.Applications.onData(function(appId, data) {
	// data received
});

Ext.space.Applications.onAlert(function(appId, alert) {
	// alert received
});

The incoming values are the same as above, with the addition of the application ID associated with each notification.

Get Settings

In order to discover the current notification settings for your application, use the following API call.

Ext.space.Notification.getNotificationSettings().then(function(settings) {
    // check for required setting in the settings object
});

The settings object contains the following boolean properties:

• sendPushNotifications - If push notifications are allowed for this application.
• clientPushNotificationSettings - If client overrides are allowed for this application.
• userAlerts - The client’s alert setting.
• userBadges - The client’s badge setting.

Application Badge

Getting the current badge of the application is available via getBadge().

Ext.space.Notification.getBadge().then(function(badge) {
    // current badge = badge
});

You can clear the application’s badge by passing null to setBadge(). Setting the badge will register the new value on the Sencha Web Application Manager server, which will proprogate to other devices that are owned by the user.

Ext.space.Notification.setBadge()
    .then(function() {
        // success
    }, function() {
        // failure
    });

Local Notification

Notifications that are pushed from server can also be sent from your application.

var alert = {
	message: 'Hello!',
	icon: 'http://someiconurl.com/caps.png',
	tags: ['local', 'sencha']
};

Ext.space.Notification.showAlert(alert)
	.then(function() {
		// success
	}, function() {
		// failure
	});