The Push API provides functionality for receiving push notifications from the Tizen push server. The push service is a client daemon that maintains a permanent connection between your device and the Tizen push server. Connection with push server is used to deliver push notifications to the application, and process the registration and deregistration requests.
To receive push notifications, follow the steps below:
For more information on the Push features, see Push Guide.
To use Push features the application needs the permission to access the Tizen Push servers.
Service Limitation:
Since: 3.0
A push service registration identifier.
typedef DOMString PushRegistrationId;
A push registration state.
enum PushRegistrationState {"REGISTERED", "UNREGISTERED"};
The PushManagerObject interface defines what is instantiated by the Tizen object from the Tizen Platform.
[NoInterfaceObject] interface PushManagerObject { readonly attribute PushManager push; };
Tizen implements PushManagerObject;
The tizen.push object allows access to the functionality of the Push API.
The PushManager interface provides methods to manage push registration and notification.
[NoInterfaceObject] interface PushManager { void register(PushRegisterSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void unregister(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void connect(PushRegistrationStateChangeCallback stateChangeCallback, PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void disconnect() raises(WebAPIException); PushRegistrationId getRegistrationId() raises(WebAPIException); void getUnreadNotifications() raises(WebAPIException); PushMessage? getPushMessage() raises(WebAPIException); };
register
Registers an application to the Tizen push server.
void register(PushRegisterSuccessCallback successCallback, optional ErrorCallback? errorCallback);
The ErrorCallback() is launched with these error types:
The connect() method must be called before calling the register() method.
Privilege level: public
Privilege: http://tizen.org/privilege/push
Remark : In order to use the push messaging service, see Push Guide.
Parameters:
Exceptions:
Code example:
// Defines the error callback. function errorCallback (response) { console.log("The following error occurred: " + response.name); } // Defines the registration success callback function registerSuccessCallback (id) { console.log("Registration succeeded with id: " + id); } // Defines the state change callback function stateChangeCallback (state) { console.log("The state is changed to: " + state); if (state == "UNREGISTERED") { // Requests application registration. tizen.push.register(registerSuccessCallback, errorCallback); } } // Defines the notification callback function notificationCallback (notification) { console.log("A notification arrives."); } // Connects to push service tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
Output example:
The state is changed to: UNREGISTERED Registration succeeded with id: 04a150867a50f48cb79695ac732cbe550b4a6782fffd23cbc14ba8dd5c5ab0025dad29a3e4ef5de8849b95b726bea7a6395c The state is changed to: REGISTERED
unregister
Unregisters an application from the Tizen push server.
void unregister(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
// Connection to push service should be established (with connect()) and application should be registered (with register()) before calling the code below. // Defines the error callback function errorCallback (response) { console.log("The following error occurred: " + response.name); } // Defines the unregistration success callback function unregisterSuccessCallback () { console.log("Unregistration succeeded."); } // Requests unregistration tizen.push.unregister(unregisterSuccessCallback, errorCallback);
Unregistration succeeded.
connect
Connects to the push service and gets state change events and push notifications.
void connect(PushRegistrationStateChangeCallback stateChangeCallback, PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback);
// Defines the state change callback function stateChangeCallback (state) { console.log("The state is changed to: " + state); } // Defines the notification callback function notificationCallback (notification) { console.log("A notification arrives."); } // Defines the error callback. function errorCallback (error) { console.log("The following error occurred: " + error.name); } // Requests for push service connection tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
The state is changed to: UNREGISTERED
disconnect
Disconnects the push service and stops receiving push notifications.
void disconnect();
// Requests disconnection tizen.push.disconnect();
getRegistrationId
Gets the push service registration ID for this application if the registration process is successful. null is returned if the application has not been registered yet.
PushRegistrationId getRegistrationId();
Return value: PushRegistrationId ID assigned by push service.
var registrationId = tizen.push.getRegistrationId(); if (registrationId != null) { console.log("The registration id: " + registrationId); }
// Defines the state change callback function stateChangeCallback (state) { console.log("The state is changed to: " + state); var id = tizen.push.getRegisterationId(); console.log("The registration ID: " + id); } // Defines the notification callback function notificationCallback (notification) { console.log("A notification arrives."); } // Requests for push service connection tizen.push.connect(stateChangeCallback, notificationCallback);
The state is changed to: UNREGISTERED The registration ID: 04a150867a50f48cb79695ac732cbe550b4a6782fffd23cbc14ba8dd5c5ab0025dad29a3e4ef5de8849b95b726bea7a6395c
getUnreadNotifications
Requests to get unread push notifications. As a consequence, the PushNotificationCallback which was set using the connectService() method will be invoked to retrieve the notifications..
void getUnreadNotifications();
The connectService() method must be called to connect to Tizen push server and receive push notifications before calling the getUnreadNotifications() method. If connectService is not called, ServiceNotAvailableError occurs. If any unread message exists, you will get unread push notification message through PushNotificationCallback of connectService(). For instance, if there are 10 unread messages, the PushNotificationCallback will be invoked 10 times.
If an application receives unread messages, the messages are removed from the system.
When an application registers with the push server to receive push notifications, the push server stores messages for the application until they are delivered. While the application is not running, messages cannot be delivered. This method allows retrieving such missed push messages. Once a missed push notification is retrieved the server deletes it from its database.
// Defines the connect success callback function notificationCallback(message) { console.log("New push message : " + message.alertMessage + ", date : " + message.date + ", data : " + message.appData); } } // Requests for push service connection tizen.push.connectService(notificationCallback); tizen.push.getUnreadNotifications();
// Defines the state change callback function stateChangeCallback (state) { console.log("The state is changed to: " + state); if (state === "REGISTERED") { // Gets unread push notifications tizen.push.getUnreadNotifications(); } } // Defines the notification callback function notificationCallback (notification) { console.log("A notification arrives."); } // Requests for push service connection tizen.push.connect(stateChangeCallback, notificationCallback);
The state is changed to: REGISTERED
getPushMessage
Gets push messages when the application is launched by the push service.
PushMessage? getPushMessage();
If the application is launched by the push service, the push service is connected when the application is launched. Therefore, you can get push messages without calling the connect() function.
If the application was not launched by the push service, this method returns null.
Return value: PushMessage The last message delivered from the push service or null.
try { var message = tizen.push.getPushMessage(); console.log('Message received from: ' + message.sender); } catch (err) { console.log('Exception - code: ' + err.name + ' message: ' + err.message); }
Message received from: xyz.AnotherApp
The PushMessage interface specifies the push message that is delivered from the push service.
[NoInterfaceObject] interface PushMessage { readonly attribute DOMString appData; readonly attribute DOMString alertMessage; readonly attribute DOMString message; readonly attribute Date date; readonly attribute DOMString sender; readonly attribute DOMString sessionInfo; readonly attribute DOMString requestId; };
// Defines the state change callback function stateChangeCallback (state) { console.log("The state is changed to: " + state); } // Defines the connect success callback function notificationCallback(noti) { console.log('notification received on ' + noti.date + ' from: ' + noti.sender); console.log('Details:'); console.log(' - data: ' + noti.appData); console.log(' - alert message: ' + noti.alertMessage); console.log(' - message: ' + noti.message); console.log(' - session: ' + noti.sessionInfo); console.log(' - request ID: ' + noti.requestId); } // Requests for push service connection tizen.push.connect(stateChangeCallback, notificationCallback);
The state is changed to: REGISTERED notification received on Thu Jan 01 2015 from: xyz.AnotherApp Details: - data: {id:asdf} - alert message: Hi - message: alertMessage=Hi - session: 002002 - request ID: 23
The PushRegisterSuccessCallback interface specifies the success callback for a push service registration request.
[Callback=FunctionOnly, NoInterfaceObject] interface PushRegisterSuccessCallback { void onsuccess(PushRegistrationId id); };
This success callback is invoked when a push service registration request is successful.
onsuccess
Called when a push service registration request is successful.
void onsuccess(PushRegistrationId id);
The PushRegistrationStateChangeCallback interface specifies the state change callback for the state change event.
[Callback=FunctionOnly, NoInterfaceObject] interface PushRegistrationStateChangeCallback { void onsuccess(PushRegistrationState state); };
This state change callback is invoked when the state of registration is changed. Moreover PushRegistrationStateChangeCallback would be called at least once, just after connection is established.
Called when the state of push registration is changed.
void onsuccess(PushRegistrationState state);
The PushNotificationCallback interface specifies the notification callback for the received push notification message.
[Callback=FunctionOnly, NoInterfaceObject] interface PushNotificationCallback { void onsuccess(PushMessage message); };
This notification callback is invoked when the push notification message arrives.
Called when the push notification message arrives.
void onsuccess(PushMessage message);
You can check if this API is supported with tizen.systeminfo.getCapability() and decide enable/disable codes that need this API.
To guarantee that the push application runs on a device with the push feature, declare the following feature requirements in the config file:
For more information, see Application Filtering.
module Push { typedef DOMString PushRegistrationId; enum PushRegistrationState {"REGISTERED", "UNREGISTERED"}; [NoInterfaceObject] interface PushManagerObject { readonly attribute PushManager push; }; Tizen implements PushManagerObject; [NoInterfaceObject] interface PushManager { void register(PushRegisterSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void unregister(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void connect(PushRegistrationStateChangeCallback stateChangeCallback, PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void disconnect() raises(WebAPIException); PushRegistrationId getRegistrationId() raises(WebAPIException); void getUnreadNotifications() raises(WebAPIException); PushMessage? getPushMessage() raises(WebAPIException); }; [NoInterfaceObject] interface PushMessage { readonly attribute DOMString appData; readonly attribute DOMString alertMessage; readonly attribute DOMString message; readonly attribute Date date; readonly attribute DOMString sender; readonly attribute DOMString sessionInfo; readonly attribute DOMString requestId; }; [Callback=FunctionOnly, NoInterfaceObject] interface PushRegisterSuccessCallback { void onsuccess(PushRegistrationId id); }; [Callback=FunctionOnly, NoInterfaceObject] interface PushRegistrationStateChangeCallback { void onsuccess(PushRegistrationState state); }; [Callback=FunctionOnly, NoInterfaceObject] interface PushNotificationCallback { void onsuccess(PushMessage message); }; };