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 the following:

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

Service architecture

To receive push notifications for your application, follow these steps:

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, follow these steps:

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:
1. 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.
2. 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.
3. 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.

Register 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);
}

/* Request application registration */
tizen.push.registerService(service, registerSuccessCallback, errorCallback);

Since Tizen 3.0:

Before registering, you must connect to the push service, follow these steps to 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. The register() method is called in the stateChangeCallback() 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.

Receive 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, these are the 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 or SILENT 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 and SILENT 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. The `alertMessage` 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.

Retrieve missed push messages

While the application is not running, messages cannot be delivered. Follow these steps 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 the getUnreadNotifications() 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.

Handle a launch by the push service

If the application is launched by the push service, follow these steps to 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);
            }
        }
    }
}

Retrieve 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, follow these steps:

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);
}

Dependencies
- Tizen 2.4 and Higher for Mobile
- Tizen 2.3.1 and Higher for Wearable
- Tizen 3.0 and Higher for TV

Push Notification

Architecture

Prerequisites

Register to the push service

Receive push notifications

Retrieve missed push messages

Handle a launch by the push service

Retrieve messages when launched by the push service

Related information