Push Notification
You can receive notifications from a push server. The push service is a client daemon that maintains a permanent connection between the device and the push server. Push enables you to push events from an application server to your application on a Tizen device. Connection with the push service is used to deliver push notifications to the application, and process the registration and deregistration requests.
The Push API is optional for Tizen Mobile, Wearable, and TV profiles, which means that it may not be supported on all mobile, wearable, and TV devices. The Push API is supported on all Tizen emulators.
Push notification helps your application server send data to your application on a device over a network, even if the application is not running. Using the push service can reduce battery consumption and data transfer.
If a push message arrives when the application is running, the message is automatically delivered to the application. If the application is not running, the push service makes a sound or vibrates and adds a ticker or a badge notification to notify the user. By touching this notification, the user can check the message. If the application server sends a message with a LAUNCH
option, the push service forcibly launches the application and hands over the message to the application.
The main features of the Push API include:
-
Registering to the push service
You can register to the push service and get the registration identifier.
-
Receiving push notifications
You can connect to the push service and start receiving push notifications.
-
Retrieving missed push messages
While the application is not running, messages cannot be delivered. You can retrieve such missed push messages later.
-
Getting push messages when the application is launched by the push service
The application can be launched by the push service. In that case, you must determine the reason for the launch, and react to it appropriately. If the application is launched due to a notification, you can retrieve and read the last message delivered from the push service.
-
Sending push notifications
The push service implements the RESTful open API for sending a push message. For more information on sending push notifications, see Push Server.
Note
Remember about security issues when sending notifications with sensitive information. For a list of strongly recommended rules, see Managing Security.
Architecture
The architecture of the Tizen Push service is described in detail in the mobile native Push guide.
Figure: Service architecture
To receive push notifications for your application:
- Request permission to access the Tizen push servers for using the push service API.
- Wait for a confirmation email for the request.
- Register the installed application on the device.
- Connect to the push service for receiving push notifications.
- Receive notifications from the push service.
Prerequisites
To enable your application to use the push functionality:
-
To use the Push API (in mobile, wearable, and TV applications), the application has to request permission by adding the following privilege to the
config.xml
file:<tizen:privilege name="http://tizen.org/privilege/push"/>
-
Make sure the following requirements are fulfilled:
-
Internet access
To connect to the Tizen push server and receive notifications from it, the target device or emulator must be able to contact any IP address with the port 5223. If you are in an enterprise network, ensure that the proxy setting in your local network allows outgoing traffic destined for this port number.
-
Package ID
When you create a project in Tizen Studio, you are given the package ID (randomly generated by Tizen Studio or entered by yourself). The Tizen push server identifies your applications using the package ID.
-
Push server access
To use the push messaging service, the application needs permission to access the Tizen push server. Request permission from the Tizen push service team using one of the following online request forms:
- Request permission for a new application
- Extend the expiration date or change the quota for an application that already has permission to use the push messaging service
When the team approves the request, you receive a push app ID corresponding to your package ID.
-
Registering to the Push Service
To receive push notifications, you must learn how to register your application to the push service:
-
Up to Tizen 2.4:
-
Define event handlers for the registration results:
/* Define the data to be used when this process is launched by the notification service */ var service = new tizen.ApplicationControl('http://tizen.org/appcontrol/operation/push_test'); /* Define the error callback */ function errorCallback(response) { console.log('The following error occurred: ' + response.name); } /* Define the registration success callback */ function registerSuccessCallback(id) { console.log('Registration succeeded with id: ' + id); }
-
Register the application for the service with the
register()
method. This operation has to be done only once./* Request application registration */ tizen.push.registerService(service, registerSuccessCallback, errorCallback);
-
-
Since Tizen 3.0:
Before registering, you must connect to the push service:
-
Define event handlers:
/* Define the error callback */ function errorCallback(response) { console.log('The following error occurred: ' + response.name); } /* Define the registration success callback */ function registerSuccessCallback(id) { console.log('Registration succeeded with id: ' + id); } /* Define the state change callback */ function stateChangeCallback(state) { console.log('The state is changed to: ' + state); if (state == 'UNREGISTERED') { /* Request application registration */ tizen.push.register(registerSuccessCallback, errorCallback); } } /* Define the notification callback */ function notificationCallback(notification) { console.log('A notification arrives.'); }
-
Connect to the push service with the
connect()
method. Theregister()
method is called in thestateChangeCallback()
callback. This operation has to be done only once./* Connect to push service */ tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
-
If the registration is successful, the registerSuccessCallback()
callback is called, and the registration ID is passed as a parameter. Any time after a successful registration, you can get the registration ID using the getRegistrationId()
method:
var registrationId = tizen.push.getRegistrationId();
if (registrationId != null) {
console.log('The registration id: ' + registrationId);
}
Since Tizen 3.0, you must connect to the push service before getting the registration ID.
Receiving Push Notifications
You can connect to the push service and start receiving push notifications with the connectService()
method up to Tizen 2.4, or with the connect()
method since Tizen 3.0. Up to Tizen 2.4, you must pass the PushNotificationCallback
listener (in mobile and wearable applications) as a parameter in the method to receive push notifications. Since Tizen 3.0, you must pass the PushRegistrationStateChangeCallback
(in mobile, wearable, and TV applications) and PushNotificationCallback
callbacks (in mobile, wearable, and TV applications) as parameters in the method. The first callback is called when the registration change state changes. This callback is called at least once, just after the connection is established. The second callback is called when notification messages arrive. You can also pass the ErrorCallback
as a parameter to be called if the connection request fails.
When a notification arrives at the device, its delivery mechanism depends on whether the application is running:
-
When the application is running
When a notification arrives to the application while it is running (precisely, the application is connected to the service), the push notification callback is called. In this callback, you can read and process the received notification as described in this use case.
-
When the application is not running
If the notification arrives when the application is not running, there are 3 ways to handle the notification:
-
Forcibly launch the application and deliver the notification to it.
This happens when the action is set to
LAUNCH
in the message field when sending the notification from the application server. When the notification action arrives at the device, the push service forcibly launches the application and delivers the notification as a bundle.For more information, see the Retrieving Messages When Launched by the Push Service use case.
-
Store the notification at the push service database and request it later when the application is launched.
This happens when the action is set to
ALERT
orSILENT
in the message field when sending the notification from the application server. When such a notification arrives at the device, the push service keeps the notification in the database and waits for the request from the application.For more information, see the Retrieving Missed Push Messages use case.
The difference between the
ALERT
andSILENT
actions is that the former shows an alert message in the quick panel and changes the badge count, while the latter does not. If the user clicks the alert message in the quick panel, the push service forcibly launches the application and delivers the notification. -
Discard the notification.
This happens when the action is set to
DISCARD
in the message field when sending the notification from the application server. When such a notification arrives at the device, the push service discards the notification unless the application is running.
-
To take advantage of the push technology, you must learn how to connect to the push service and receive push notifications:
-
Define the event handlers for the push connection. The push notifications are delivered in the success event handler.
function errorCallback(response) { console.log('The following error occurred: ' + response.name); } function notificationCallback(message) { console.log('New push message: ' + message.alertMessage + ', date: ' + message.date + ', data: ' + message.appData); } /* Since Tizen 3.0, you must provide PushRegistrationStateChangeCallback */ /* Define the state change callback */ function stateChangeCallback(state) { console.log('The state is changed to: ' + state); }
The following table lists the fields available in the notification callback.
Table: Push message key-value pairs
Key Value Description appData
String, less than 1 KB Message payload.
The applications can use this field to carry their own data.alertMessage
String, up to 127 bytes Alert message shown to the user in the quick panel.
ThealertMessage
field takes effect only when the application is not running (more precisely, when the application is not connected to the push service). If a notification arrives at the device where the application is running, the push service delivers the notification directly to the application. It does not show the alert message in the quick panel or increase the badge count.message
String Full push notification message.
For example:"badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi"
date
Date Date and time when a push notification message was received. sender
String Name of the notification sender. sessionInfo
String Session information for the notification. requestId
String Request ID assigned by the sender. type
Number Type value assigned by the sender. -
Request the push service connection:
-
Up to Tizen 2.4:
tizen.push.connectService(notificationCallback, errorCallback);
-
Since Tizen 3.0:
tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
If the connection is established, you start receiving push notifications.
-
To stop listening for new push messages, call the disconnectService()
(up to Tizen 2.4) or disconnect()
(since Tizen 3.0) method:
/* Up to Tizen 2.4 */
tizen.push.disconnectService();
/* Since Tizen 3.0 */
tizen.push.disconnect();
To learn how send a simple push notification to the device, see Sending Push Notifications. For advanced features in sending notifications, see the Push Server guide for server developers.
Retrieving Missed Push Messages
While the application is not running, messages cannot be delivered. To retrieve such missed push messages:
-
Up to Tizen 2.4:
-
Call the
connectService()
method to connect to the Tizen push server and receive new push notifications:/* Method to be called when the notification message arrives */ function notificationCallback(message) { console.log('New push message: ' + message.alertMessage + ', date: ' + message.date + ', data: ' + message.appData); } tizen.push.connectService(notificationCallback);
-
Retrieve any unread messages:
tizen.push.getUnreadNotifications();
-
-
Since Tizen 3.0:
Call the
connect()
method to connect to the Tizen push server, and retrieve any unread messages with thegetUnreadNotifications()
method in the state change callback when the application is registered:/* Define the error callback */ function errorCallback(response) { console.log('The following error occurred: ' + response.name); } /* Define the registration success callback */ function registerSuccessCallback(id) { console.log('Registration succeeded with id: ' + id); } /* Define the state change callback */ function stateChangeCallback(state) { console.log('The state is changed to: ' + state); if (state === 'UNREGISTERED') { /* Request application registration */ tizen.push.register(registerSuccessCallback, errorCallback); } else if (state === 'REGISTERED') { /* Gets unread push notifications */ tizen.push.getUnreadNotifications(); } } /* Define the notification callback */ function notificationCallback(notification) { console.log('A notification arrives.'); } tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
The notification callback passed to the connectService()
(up to Tizen 2.4) or connect()
(since Tizen 3.0) method is called for every unread message.
Handling a Launch by the Push Service
If the application is launched by the push service, determine the reason for the application launch and react to it appropriately:
-
Get the requested application control with the
getRequestedAppControl()
method:var requestedAppControl = tizen.application.getCurrentApplication().getRequestedAppControl().appControl;
-
Determine the reason for the application launch. If the reason for the launch is a notification, retrieve the latest push message.
for (var i = 0; i < requestedAppControl.data.length; ++i) { if (requestedAppControl.data[i].key === 'http://tizen.org/appcontrol/data/push/launch_type') { /* Launch type is 'registration_change' or 'notification' */ var appData = requestedAppControl.data[i].value[0]; console.log('launch_type: ' + appData); if (appData === 'registration_change') { /* Launched due to change in the registration state */ } else if (appData === 'notification') { /* Launched due to a notification */ try { /* Retrieve the latest message */ var pushMessage = tizen.push.getPushMessage(); /* Handle the retrieved message */ } catch (error) { console.log(error.name + ': ' + error.message); } } } }
Retrieving Messages When Launched by the Push Service
If the application is launched by the push service due to a notification, use the getPushMessage()
method to return the last undelivered push message. If none exists, the method returns NULL
.
To retrieve and read the last message:
-
Retrieve the message:
var pushMessage = tizen.push.getPushMessage();
-
Read the message content:
if (pushMessage) { console.log('notification received on ' + pushMessage.date + ' from: ' + pushMessage.sender); console.log('Details:'); console.log(' - data: ' + pushMessage.appData); console.log(' - alert message: ' + pushMessage.alertMessage); console.log(' - message: ' + pushMessage.message); console.log(' - session: ' + pushMessage.sessionInfo); console.log(' - request ID: ' + pushMessage.requestId); console.log(' - type: ' + pushMessage.type); }
Related Information
- Dependencies
- Tizen 2.4 and Higher for Mobile
- Tizen 2.3.1 and Higher for Wearable
- Tizen 3.0 and Higher for TV