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

• 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: 3.0

Summary of Interfaces and Methods

Interface	Method
PushManagerObject
PushManager	void register (PushRegisterSuccessCallback successCallback, optional ErrorCallback? errorCallback) void unregister (optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) void connect (PushRegistrationStateChangeCallback stateChangeCallback, PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback) void disconnect () PushRegistrationId getRegistrationId () void getUnreadNotifications () PushMessage? getPushMessage ()
PushMessage
PushRegisterSuccessCallback	void onsuccess (PushRegistrationId id)
PushRegistrationStateChangeCallback	void onsuccess (PushRegistrationState state)
PushNotificationCallback	void onsuccess (PushMessage message)

1. Type Definitions

1.1. PushRegistrationId

A push service registration identifier.

typedef DOMString PushRegistrationId;

Since: 3.0

1.2. PushRegistrationState

A push registration state.

enum PushRegistrationState {"REGISTERED", "UNREGISTERED"};

Since: 3.0

• REGISTERED - The application is registered to the push server.
• UNREGISTERED - The application is not registered to the push server.

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: 3.0

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

2.2. PushManager

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

Since: 3.0

Methods

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

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.

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

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

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: 3.0

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

Output example:

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

Since: 3.0

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

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

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

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 DOMString message;

		readonly attribute Date date;

		readonly attribute DOMString sender;

		readonly attribute DOMString sessionInfo;

		readonly attribute DOMString requestId;
};

Since: 3.0

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: 3.0

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

• readonly DOMString message
  
  An attribute to store the full push notification message.
  
  Since: 3.0

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

• readonly DOMString sender
  
  The name of the sender of the notification.
  
  Since: 3.0

• readonly DOMString sessionInfo
  
  The session information of the notification.
  
  Since: 3.0

• readonly DOMString requestId
  
  The 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

The PushRegisterSuccessCallback interface specifies the success callback for a push service registration request.

[Callback=FunctionOnly, NoInterfaceObject]
interface PushRegisterSuccessCallback {
		void onsuccess(PushRegistrationId id);
};

Since: 3.0

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: 3.0

Parameters:

• id: The registration ID.

2.5. PushRegistrationStateChangeCallback

The PushRegistrationStateChangeCallback interface specifies the state change callback for the state change event.

[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

The PushNotificationCallback interface specifies the notification callback for the received push notification message.

[Callback=FunctionOnly, NoInterfaceObject]
interface PushNotificationCallback {
		void onsuccess(PushMessage message);
};

Since: 3.0

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: 3.0

Parameters:

• message: The received push notification message.

3. Related Feature

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:

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

For more information, see Application Filtering.

4. Full WebIDL

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

};