Push API
To receive push notifications, follow the steps below:
- Connecting to the push service
- Registering your application, if the application has not been registered yet
- Getting notification data
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:
- Size of a push message is limited: alertMessage up to 127 bytes, and appData (payload data) less than 1 KB.
- Push service does not guarantee delivery and order of push messages.
Since: 2.1
Table of Contents
- 1. Type Definitions
- 1.1. PushRegistrationId
- 1.2. PushRegistrationState
- 2. Interfaces
- 2.1. PushManagerObject
- 2.2. PushManager
- 2.3. PushMessage
- 2.4. PushRegisterSuccessCallback
- 2.5. PushRegistrationStateChangeCallback
- 2.6. PushNotificationCallback
- 3. Related Feature
- 4. Full WebIDL
Summary of Interfaces and Methods
Interface | Method |
---|---|
PushManagerObject | |
PushManager |
void connect (PushRegistrationStateChangeCallback stateChangeCallback, PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback)
void disconnect ()
void getUnreadNotifications ()
|
PushMessage | |
PushRegisterSuccessCallback | void onsuccess (PushRegistrationId id) |
PushRegistrationStateChangeCallback | void onsuccess (PushRegistrationState state) |
PushNotificationCallback | void onsuccess (PushMessage message) |
1. Type Definitions
2. Interfaces
2.1. PushManagerObject
[NoInterfaceObject] interface PushManagerObject { readonly attribute PushManager push; };
Tizen implements PushManagerObject;
Since: 2.1
The tizen.push object allows access to the functionality of the Push API.
Attributes
-
readonly
PushManager pushObject representing a push manager.
Since: 2.1
2.2. PushManager
[NoInterfaceObject] interface PushManager { void registerService(ApplicationControl appControl, PushRegisterSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void register(PushRegisterSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void unregisterService(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void unregister(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void connectService(PushNotificationCallback notificationCallback) raises(WebAPIException); void connect(PushRegistrationStateChangeCallback stateChangeCallback, PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void disconnectService() raises(WebAPIException); void disconnect() raises(WebAPIException); PushRegistrationId getRegistrationId() raises(WebAPIException); void getUnreadNotifications() raises(WebAPIException); PushMessage? getPushMessage() raises(WebAPIException); };
Since: 2.1
Methods
-
registerService
-
Registers an application to the Tizen push server.
Deprecated. This function has been deprecated since 3.0. Use the register() function instead.
void registerService(ApplicationControl appControl, PushRegisterSuccessCallback successCallback, optional ErrorCallback? errorCallback);
Since: 2.1
The ErrorCallback() is launched with these error types:
- InvalidValuesError - If any of the input parameters contain an invalid value.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/push
Remark: In order to use the push messaging service, see Push Guide.
Parameters:
-
appControl:
The data to deliver via notification service when the process is not running.
For more information, see Application API. - successCallback: The method to be called when the registration request succeeds.
- errorCallback [optional] [nullable]: The method to be called when the registration request fails.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidValuesError, if any input parameters do not contain a valid value.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurs.
Code example:
/* Defines the data to be used when this process is launched by notification service. */ var service = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/push_test"); /* 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); } /* Requests registration. */ tizen.push.registerService(service, registerSuccessCallback, errorCallback);
-
register
-
Registers an application to the Tizen push server.
void register(PushRegisterSuccessCallback successCallback, optional ErrorCallback? errorCallback);
Since: 3.0
The ErrorCallback() is launched with these error types:
- TimeoutError - If the operation timed out.
- AbortError - If the operation cannot be finished properly.
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:
- successCallback: The callback to be called when the registration request succeeds.
- errorCallback [optional] [nullable]: The callback to be called when the registration request fails.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type InvalidStateError, if the application is not connected to the push service.
with error type AbortError, if the operation cannot be finished properly.
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
-
unregisterService
-
Unregisters an application from the Tizen push server.
Deprecated. This function has been deprecated since 3.0. Use the unregister() function instead.
void unregisterService(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 2.1
The ErrorCallback() is launched with these error types:
- UnknownError - If an unknown error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/push
Parameters:
- successCallback [optional] [nullable]: The method to be called when the request is successfully unregistered.
- errorCallback [optional] [nullable]: The method to be called when the unregistration request fails.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidValuesError, if any input parameters do not contain a valid value.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurs.
Code example:
/* 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.unregisterService(unregisterSuccessCallback, errorCallback);
-
unregister
-
Unregisters an application from the Tizen push server.
void unregister(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 3.0
The ErrorCallback() is launched with these error types:
- TimeoutError - If the operation timed out.
- AbortError - If the operation cannot be finished properly.
Privilege level: public
Privilege: http://tizen.org/privilege/push
Parameters:
- successCallback [optional] [nullable]: The callback to be called when the unregistration request succeeds.
- errorCallback [optional] [nullable]: The callback to be called when the unregistration request fails.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type InvalidStateError, if the application is not connected to the push service.
with error type AbortError, if the operation cannot be finished properly.
Code example:
/* 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);
Output example:
Unregistration succeeded.
-
connectService
-
Connects to the push service and receives push notifications.
Deprecated. This function has been deprecated since 3.0. Use the connect() function instead.
void connectService(PushNotificationCallback notificationCallback);
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/push
Remark: If the application calling the connectService() method has not been registered to the Tizen push server, the registerService() method must be called before calling the connectService() method.
Parameters:
- notificationCallback: The method to be called when the notification message arrives.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidValuesError, if any input parameters do not contain a valid value.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurs.
Code example:
/* Defines the connect success callback. */ function notificationCallback(noti) { console.log("Notification received with alert message: " + noti.alertMessage); } /* Defines the data to be used when this process is launched by notification service. */ var service = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/push_test"); /* 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); /* Requests for push service connection. */ tizen.push.connectService(notificationCallback); } /* Requests registration. */ tizen.push.registerService(service, registerSuccessCallback, errorCallback);
-
connect
-
Connects to the push service and gets state change events and push notifications.
void connect(PushRegistrationStateChangeCallback stateChangeCallback, PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback);
Since: 3.0
The ErrorCallback() is launched with these error types:
- AbortError - If the operation cannot be finished properly.
Privilege level: public
Privilege: http://tizen.org/privilege/push
Parameters:
- stateChangeCallback: The callback to be called when the state of registration is changed. The callback would be called at least once, just after connection is established.
- notificationCallback: The callback to be called when the notification message arrives.
- errorCallback [optional] [nullable]: The callback to be called when the connect request fails.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type AbortError, if the operation cannot be finished properly.
Code example:
/* 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);
Output example:
The state is changed to: UNREGISTERED
-
disconnectService
-
Disconnects the push service and stops receiving push notifications.
Deprecated. This function has been deprecated since 3.0. Use the disconnect() function instead.
void disconnectService();
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/push
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type AbortError, if the operation cannot be finished properly.
Code example:
/* Requests disconnection. */ tizen.push.disconnectService();
- WebAPIException
-
disconnect
-
Disconnects the push service and stops receiving push notifications.
void disconnect();
Since: 3.0
Privilege level: public
Privilege: http://tizen.org/privilege/push
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurs.
Code example:
/* Requests disconnection. */ tizen.push.disconnect();
- WebAPIException
-
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();
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/push
Return value:
-
PushRegistrationId:
ID assigned by push service.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurs.
Code example:
var registrationId = tizen.push.getRegistrationId(); if (registrationId != null) { console.log("The registration id: " + registrationId); }
Code example:
/* Defines the state change callback. */ function stateChangeCallback(state) { console.log("The state is changed to: " + state); var id = tizen.push.getRegistrationId(); 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);
Output example:
The state is changed to: UNREGISTERED The registration ID: 04a150867a50f48cb79695ac732cbe550b4a6782fffd23cbc14ba8dd5c5ab0025dad29a3e4ef5de8849b95b726bea7a6395c
- WebAPIException
-
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();
Since: 2.3
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.
Privilege level: public
Privilege: http://tizen.org/privilege/push
Exceptions:
- WebAPIException
with error type ServiceNotAvailableError, if the network is unreachable for some reason(e.g disconnected to the Tizen push server)
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurs.
Code example:
/* 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);
Output example:
The state is changed to: REGISTERED
- WebAPIException
-
getPushMessage
-
Gets push messages when the application is launched by the push service.
PushMessage? getPushMessage();
Since: 3.0
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.
Privilege level: public
Privilege: http://tizen.org/privilege/push
Return value:
-
PushMessage [nullable]:
The last message delivered from the push service or null.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type AbortError, if the operation cannot be finished properly.
Code example:
try { var message = tizen.push.getPushMessage(); console.log("Message received from: " + message.sender); } catch (err) { console.log("Exception - code: " + err.name + " message: " + err.message); }
Output example:
Message received from: xyz.AnotherApp
- WebAPIException
2.3. PushMessage
[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; };
Since: 2.1
Attributes
-
readonly
DOMString appDataAn attribute to store the push notification data.
This data is the message that the sender wants to send and its length must be less than 1 KB.
Since: 2.1
-
readonly
DOMString alertMessageAn attribute to store the push notification message that may include an alert message to the user.
Since: 2.1
-
readonly
DOMString messageAn attribute to store the full push notification message.
Since: 3.0
-
readonly
Date dateAn attribute to store the date/time when a push notification message is received.
Since: 2.1
-
readonly
DOMString senderThe name of the sender of the notification.
Since: 3.0
-
readonly
DOMString sessionInfoThe session information of the notification.
Since: 3.0
-
readonly
DOMString requestIdThe request ID assigned by the sender.
Since: 3.0
Code example:
/* 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);
Output example:
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
2.4. PushRegisterSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface PushRegisterSuccessCallback { void onsuccess(PushRegistrationId id); };
Since: 2.1
This success callback is invoked when a push service registration request is successful.
Methods
-
onsuccess
-
Called when a push service registration request is successful.
void onsuccess(PushRegistrationId id);
Since: 2.1
Parameters:
- id: The registration ID.
2.5. PushRegistrationStateChangeCallback
[Callback=FunctionOnly, NoInterfaceObject] interface PushRegistrationStateChangeCallback { void onsuccess(PushRegistrationState state); };
Since: 3.0
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.
Methods
-
onsuccess
-
Called when the state of push registration is changed.
void onsuccess(PushRegistrationState state);
Since: 3.0
Parameters:
- state: The state of push registration.
2.6. PushNotificationCallback
[Callback=FunctionOnly, NoInterfaceObject] interface PushNotificationCallback { void onsuccess(PushMessage message); };
Since: 2.1
This notification callback is invoked when the push notification message arrives.
Methods
-
onsuccess
-
Called when the push notification message arrives.
void onsuccess(PushMessage message);
Since: 2.1
Parameters:
- message: The received push notification message.
3. Related Feature
To guarantee that the push application runs on a device with the push feature, declare the following feature requirements in the config file:
4. Full WebIDL
module Push { typedef DOMString PushRegistrationId; enum PushRegistrationState { "REGISTERED", "UNREGISTERED" }; Tizen implements PushManagerObject; [NoInterfaceObject] interface PushManagerObject { readonly attribute PushManager push; }; [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); }; };