Push API

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 service is used to deliver push notifications to the application, and process the registration and deregistration requests. If the application is connected, the push service passes the notification data over the connection. Otherwise, the push service posts a UI notification with the data. It will be delivered when a user launches the application by selecting the posting.

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.3.1

Table of Contents

Summary of Interfaces and Methods

Interface Method
PushManagerObject
PushManager
void registerService (ApplicationControl appControl, PushRegisterSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void unregisterService (optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void connectService (PushNotificationCallback notificationCallback)
PushMessage
PushRegisterSuccessCallback
PushNotificationCallback
void onsuccess (PushMessage message)

1. Type Definitions

1.1. PushRegistrationId

A push service registration identifier. 
  typedef DOMString PushRegistrationId;

Since: 2.3.1

2. Interfaces

2.1. PushManagerObject

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;

Since: 2.3.1

The tizen.push object allows access to the functionality of the Push API.

Attributes

  • readonly PushManager push
    Object representing a push manager.

    Since: 2.3.1

2.2. PushManager

The PushManager interface provides methods to manage push registration and notification. 
  [NoInterfaceObject] interface PushManager {
    void registerService(ApplicationControl appControl, PushRegisterSuccessCallback successCallback,
                         optional ErrorCallback? errorCallback) raises(WebAPIException);
    void unregisterService(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
    void connectService(PushNotificationCallback notificationCallback) raises(WebAPIException);
    void disconnectService() raises(WebAPIException);
    PushRegistrationId getRegistrationId() raises(WebAPIException);
    void getUnreadNotifications() raises(WebAPIException);
  };

Since: 2.3.1

Methods

registerService
Registers an application to the Tizen push server. 
void registerService(ApplicationControl appControl, PushRegisterSuccessCallback successCallback,
                     optional ErrorCallback? errorCallback);

Since: 2.3.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);
unregisterService
Unregisters an application from the Tizen push server. 
void unregisterService(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 2.3.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);
connectService
Connects to the push service and receives push notifications. 
void connectService(PushNotificationCallback notificationCallback);

Since: 2.3.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);
disconnectService
Disconnects the push service and stops receiving push notifications. 
void disconnectService();

Since: 2.3.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 UnknownError, if any other error occurs.

Code example:

/* Requests disconnection. */
tizen.push.disconnectService();
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.3.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);
}
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.1

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

2.3. PushMessage

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 Date date;
  };

Since: 2.3.1

Attributes

  • readonly DOMString appData
    An 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.3.1

  • readonly DOMString alertMessage
    An attribute to store the push notification message that may include an alert message to the user.

    Since: 2.3.1

  • readonly Date date
    An attribute to store the date/time when a push notification message is received.

    Since: 2.3.1

2.4. PushRegisterSuccessCallback

The PushRegisterSuccessCallback interface specifies the success callback for a push service registration request. 
  [Callback=FunctionOnly, NoInterfaceObject] interface PushRegisterSuccessCallback {
    void onsuccess(PushRegistrationId id);
  };

Since: 2.3.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.3.1

Parameters:

  • id: The registration ID.

2.5. PushNotificationCallback

The PushNotificationCallback interface specifies the notification callback for the received push notification message. 
  [Callback=FunctionOnly, NoInterfaceObject] interface PushNotificationCallback {
    void onsuccess(PushMessage message);
  };

Since: 2.3.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.3.1

Parameters:

  • message: The received push notification message.

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee that the push application runs on a device with the push feature, declare the following feature requirements in the config file:

  • http://tizen.org/feature/network.push

    • For more information, see Application Filtering.

    4. Full WebIDL

    module Push {
  typedef DOMString PushRegistrationId;
  Tizen implements PushManagerObject;
  [NoInterfaceObject] interface PushManagerObject {
    readonly attribute PushManager push;
  };
  [NoInterfaceObject] interface PushManager {
    void registerService(ApplicationControl appControl, PushRegisterSuccessCallback successCallback,
                         optional ErrorCallback? errorCallback) raises(WebAPIException);
    void unregisterService(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
    void connectService(PushNotificationCallback notificationCallback) raises(WebAPIException);
    void disconnectService() raises(WebAPIException);
    PushRegistrationId getRegistrationId() raises(WebAPIException);
    void getUnreadNotifications() raises(WebAPIException);
  };
  [NoInterfaceObject] interface PushMessage {
    readonly attribute DOMString appData;
    readonly attribute DOMString alertMessage;
    readonly attribute Date date;
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface PushRegisterSuccessCallback {
    void onsuccess(PushRegistrationId id);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface PushNotificationCallback {
    void onsuccess(PushMessage message);
  };
};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.