<li><a href="#Registering">Registering to the Push Service</a></li>
<li><a href="#Receiving">Receiving Push Notifications</a></li>
<li><a href="#UnreadNotifications">Retrieving Missed Push Messages</a></li>
+ <li><a href="#HandlingWhenLaunched">Handling a Launch by the Push Service</a></li>
<li><a href="#GetPushMessage">Retrieving Messages When Launched by the Push Service</a></li>
</ul>
<p class="toc-title">Related Info</p>
<div id="container"><div id="contents"><div class="content">
<h1>Push Notification</h1>
- <p>Tizen enables you to 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 server is used to deliver push notifications to the application, and process the registration and deregistration requests.</p>
+ <p>Tizen enables you to 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.</p>
<p>This feature is supported in mobile and wearable applications only.</p>
<li><a href="#Registering">Registering to the push service</a>
<p>You can register or deregister the application for the push service. If the registration process is successful, it returns the registration identifier through the <span style="font-family: Courier New,Courier,monospace">PushRegisterSuccessCallback</span> listener (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/push.html#PushRegisterSuccessCallback">mobile</a> and <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/push.html#PushRegisterSuccessCallback">wearable</a> applications). The application server needs the registration ID to send notifications to the application installed on a specific device.</p></li>
<li><a href="#Receiving">Receiving push notifications</a>
- <p>You can connect to the push service and start receiving push notifications with the <span style="font-family: Courier New,Courier,monospace">connectService()</span> method. You must pass the <span style="font-family: Courier New,Courier,monospace">PushNotificationCallback</span> listener (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/push.html#PushNotificationCallback">mobile</a> and <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/push.html#PushNotificationCallback">wearable</a> applications) as a parameter in the method to receive push notifications.</p> </li>
+ <p>You can connect to the push service and start receiving push notifications with the <span style="font-family: Courier New,Courier,monospace">connectService()</span> method up to Tizen 2.4, or with <span style="font-family: Courier New,Courier,monospace">connect()</span> method since Tizen 3.0. Up to Tizen 2.4, you must pass the <span style="font-family: Courier New,Courier,monospace">PushNotificationCallback</span> listener (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/push.html#PushNotificationCallback">mobile</a> and <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/push.html#PushNotificationCallback">wearable</a> applications) as a parameter in the method to receive push notifications. Since Tizen 3.0, you must pass the <span style="font-family: Courier New,Courier,monospace">PushRegistrationStateChangeCallback</span> (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/push.html#PushRegistrationStateChangeCallback">mobile</a> applications) and <span style="font-family: Courier New,Courier,monospace">PushNotificationCallback</span> callbacks 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 <span style="font-family: Courier New,Courier,monospace">ErrorCallback</span> as a parameter to be called if the connection request fails.</p> </li>
<li><a href="#UnreadNotifications">Retrieving missed push messages</a>
<p>While the application is not running, messages cannot be delivered. You can retrieve such missed push messages later on.</p></li>
- <li><a href="#GetPushMessage">Getting push messages when the application is launched by the push service</a>
- <p>The application can be launched by the push service. In that case, you can get the last message delivered from the push service.</p></li>
+ <li><a href="#HandlingWhenLaunched">Reacting to a launch by the push service</a>
+ <p>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 <a href="#GetPushMessage">retrieve and read the last message delivered from the push service</a>.</p></li>
<li>Sending push notifications
<p>The push service implements the RESTful open API for sending a push message. For more information on sending push notifications, see <a href="../../native/messaging/push_server_n.htm">Push Server</a>.</p>
</li>
<p>Become familiar with the Push API basics by learning about:</p>
<ul>
<li><a href="#prerequisites">Prerequisites</a> <p>Prepare your application to use the push functionality.</p></li>
- <li><a href="#Registering">Registering to the Push Service</a> <p>Register to the push service and get the registration identifier.</p> </li>
+ <li><a href="#Registering">Registering to the Push Service</a> <p>Register to the push service and get the registration identifier. Since Tizen 3.0, you must connect to the push service before registering.</p> </li>
<li><a href="#Receiving">Receiving Push Notifications</a> <p>Connect to the push service and start receiving push notifications.</p></li>
<li><a href="#UnreadNotifications">Retrieving Missed Push Messages</a> <p>Retrieve push messages that have been missed because the messages cannot be delivered while the application is not running.</p></li>
- <li><a href="#GetPushMessage">Retrieving Messages When Launched by the Push Service</a> <p>When the application is launched by the push service, retrieve the last message delivered from the push service.</p></li>
+ <li><a href="#HandlingWhenLaunched">Handling a Launch by the Push Service</a> <p>When the application is launched by the service, determine the launch type (reason for the launch) and react to it appropriately.</p></li>
+ <li><a href="#GetPushMessage">Retrieving Messages When Launched by the Push Service</a> <p>When the application is launched by the push service due to a notification, retrieve the last message delivered from the push service.</p></li>
</ul>
<h2 id="prerequisites">Prerequisites</h2>
</table>
</li></ul>
</li>
-
</ol>
-
<h2 id="Registering" name="Registering">Registering to the Push Service</h2>
-
- <p>To receive push notifications, you must learn how to register your application to the push service:</p>
+ <p>To receive push notifications, you must learn how to register your application to the push service:</p>
+ <ul>
+ <li>
+ <p>Up to Tizen 2.4:</p>
<ol>
<li><p>Define event handlers for the registration results:</p>
<pre class="prettyprint">
+/* 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);
+ console.log("The following error occurred: " + response.name);
}
/* Define the registration success callback */
}
</pre>
</li>
- <li><p>Register the application for the service with the <span style="font-family: Courier New,Courier,monospace">register()</span> method. This operation only needs to be done once.</p>
+ <li><p>Register the application for the service with the <span style="font-family: Courier New,Courier,monospace">register()</span> method. This operation has to be done only once.</p>
<pre class="prettyprint">
/* Request application registration */
-tizen.push.register(registerSuccessCallback, errorCallback);
+tizen.push.registerService(service, registerSuccessCallback, errorCallback);
</pre>
-<p>If the registration is successful, the <span style="font-family: Courier New,Courier,monospace;">registerSuccessCallback()</span> is called, and the registration ID is passed as a parameter.</p></li>
- </ol>
+</li>
+ </ol>
+ </li>
+ <li>
+ <p>Since Tizen 3.0:</p>
+ <p>Before registering, you must connect to the push service:</p>
+ <ol>
+ <li><p>Define event handlers:</p>
+ <pre class="prettyprint">
+/* 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);
+ }
+}
- <p>Any time after a successful registration, you can get the registration ID using the <span style="font-family: Courier New,Courier,monospace;">getRegistrationId()</span> method:</p>
+/* Define the notification callback */
+function notificationCallback(notification)
+{
+ console.log("A notification arrives.");
+}
+</pre>
+ </li>
+ <li><p>Connect to the push service with the <span style="font-family: Courier New,Courier,monospace">connect()</span> method. The <span style="font-family: Courier New,Courier,monospace">register()</span> method is called in the <span style="font-family: Courier New,Courier,monospace">stateChangeCallback()</span> callback. This operation has to be done only once.</p>
+ <pre class="prettyprint">
+/* Connect to push service */
+tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
+</pre>
+</li>
+ </ol>
+</li>
+</ul>
+ <p>If the registration is successful, the <span style="font-family: Courier New,Courier,monospace;">registerSuccessCallback()</span> 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 <span style="font-family: Courier New,Courier,monospace;">getRegistrationId()</span> method:</p>
<pre class="prettyprint">
var registrationId = tizen.push.getRegistrationId();
if (registrationId != null)
console.log("The registration id: " + registrationId);
}
</pre>
+<p>Since Tizen 3.0, you must connect to the push service before getting the registration ID.</p>
+
<h2 id="Receiving" name="Receiving">Receiving Push Notifications</h2>
<pre class="prettyprint">
function errorCallback(response)
{
- console.log('The following error occurred: ' + response.name);
+ console.log('The following error occurred: ' + response.name);
}
function notificationCallback(message)
{
- console.log("New push message : " + message.alertMessage + ", date : " + message.date + ", data : " + message.appData);
+ 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);
}
</pre>
<p>The following table lists the fields available in the notification callback.</p>
</li>
<li>
- <p>Request the push service connection with the <span style="font-family: Courier New,Courier,monospace">connectService()</span> method:</p>
+ <p>Request the push service connection:</p>
+ <ul>
+ <li>
+<p>Up to Tizen 2.4:</p>
<pre class="prettyprint">
tizen.push.connectService(notificationCallback, errorCallback);
</pre>
+</li>
+<li>
+<p>Since Tizen 3.0:</p>
+<pre class="prettyprint">
+tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
+</pre>
+</li>
+</ul>
<p>If the connection is established, you start receiving push notifications.</p>
</li>
</ol>
- <p>To stop listening for new push messages, call the <span style="font-family: Courier New,Courier,monospace">disconnectService()</span> method:</p>
+ <p>To stop listening for new push messages, call the <span style="font-family: Courier New,Courier,monospace">disconnectService()</span> method up to Tizen 2.4 or the <span style="font-family: Courier New,Courier,monospace">disconnect()</span> method since Tizen 3.0:</p>
<pre class="prettyprint">
+/* Up to Tizen 2.4 */
tizen.push.disconnectService();
+
+/* Since Tizen 3.0 */
+tizen.push.disconnect();
</pre>
<p>To learn how send a simple push notification to the device, see <a href="../../native/messaging/push_n.htm#send">Sending Push Notifications</a>. For advanced features in sending notifications, see the <a href="../../native/messaging/push_server_n.htm">Push Server</a> guide for server developers.</p>
<h2 id="UnreadNotifications">Retrieving Missed Push Messages</h2>
<p>While the application is not running, messages cannot be delivered. To retrieve such missed push messages:</p>
+<ul>
+ <li>
+<p>Up to Tizen 2.4:</p>
<ol>
- <li>Call the <span style="font-family: Courier New,Courier,monospace">connectService()</span> method to connect to the Tizen push server and receive push notifications, before calling the <span style="font-family: Courier New,Courier,monospace">getUnreadNotifications()</span> method.
+<li>Call the <span style="font-family: Courier New,Courier,monospace">connectService()</span> method to connect to the Tizen push server and receive new push notifications:
<pre class="prettyprint">
/* Method to be called when the notification message arrives */
function notificationCallback(message)
}
tizen.push.connectService(notificationCallback);
-</pre>
- </li>
- <li>Receive the unread messages:
-
<pre class="prettyprint">
+</pre>
+</li>
+<li>Retrieve any unread messages:
+<pre class="prettyprint">
tizen.push.getUnreadNotifications();
</pre>
-<p>The notification callback passed to the <span style="font-family: Courier New,Courier,monospace">connectService()</span> method is called for every unread message.</p>
- </li>
+</li>
+</ol>
+</li>
+<li>
+
+<p>Since Tizen 3.0:</p>
+<p>Call the <span style="font-family: Courier New,Courier,monospace">connect()</span> method to connect to the Tizen push server, and retrieve any unread messages with the <span style="font-family: Courier New,Courier,monospace">getUnreadNotifications()</span> method in the state change callback when the application is registered:</p>
+<pre class="prettyprint">
+/* 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);
+</pre>
+</li>
+
+</ul>
+<p>The notification callback passed to the <span style="font-family: Courier New,Courier,monospace">connectService()</span> (up to Tizen 2.4) or <span style="font-family: Courier New,Courier,monospace">connect()</span> (since Tizen 3.0) method is called for every unread message.</p>
+
+<h2 id="HandlingWhenLaunched">Handling a Launch by the Push Service</h2>
+<p>If the application is launched by the push service, determine the reason for the application launch and react to it appropriately:</p>
+
+<ol>
+<li>Get the requested application control with the <span style="font-family: Courier New,Courier,monospace">getRequestedAppControl()</span> method:
+<pre class="prettyprint">
+var requestedAppControl = tizen.application.getCurrentApplication().getRequestedAppControl().appControl;
+</pre></li>
+<li>Determine the reason for the application launch. If the reason for the launch is a notification, retrieve the latest push message.
+<pre class="prettyprint">
+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();
+ /* <a href="#GetPushMessage">Handle the retrieved message</a> */
+ }
+ catch (error)
+ {
+ console.log(error.name + ': ' + error.message);
+ }
+ }
+ }
+}
+</pre></li>
</ol>
<h2 id="GetPushMessage">Retrieving Messages When Launched by the Push Service</h2>
-<p>If the application is launched by the push service, use the <span style="font-family: Courier New,Courier,monospace">getPushMessage()</span> method to return the last undelivered push message. If none exists, it returns <span style="font-family: Courier New,Courier,monospace">NULL</span>.</p>
+<p>If the application is launched by the push service due to a notification, use the <span style="font-family: Courier New,Courier,monospace">getPushMessage()</span> method to return the last undelivered push message. If none exists, the function returns <span style="font-family: Courier New,Courier,monospace">NULL</span>.</p>
-<p>To retrieve the last message:</p>
+<p>To retrieve and read the last message:</p>
<ol>
<li>Retrieve the message:
<pre class="prettyprint">
-var message = tizen.push.getPushMessage();
+var pushMessage = tizen.push.getPushMessage();
</pre></li>
<li>Read the message content:
<pre class="prettyprint">
-if (message)
+if (pushMessage)
{
- console.log('notification received on ' + message.date + ' from: ' + message.sender);
+ console.log('notification received on ' + pushMessage.date + ' from: ' + pushMessage.sender);
console.log('Details:');
- console.log(' - data: ' + message.appData);
- console.log(' - alert message: ' + message.alertMessage);
- console.log(' - message: ' + message.message);
- console.log(' - session: ' + message.sessionInfo);
- console.log(' - request ID: ' + message.requestId);
- console.log(' - type: ' + message.type);
+ 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);
}
</pre></li>
</ol>
</script>
</body>
-</html>
\ No newline at end of file
+</html>
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 in order to process your registration
-and deregistration requests and deliver push notifications to applications on a device.
+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.
</div>
<div class="description">
<p>
-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.
- </p>
- <p>
To receive push notifications, follow the steps below:
</p>
<ul>
<li>
-Get administrative permission for an application on your device </li>
- <li>
-Register the application </li>
+Connecting to the push service </li>
<li>
-Connect to the push service </li>
+Registering your application, if the application has not been registered yet </li>
<li>
-Get notification data </li>
+Getting notification data </li>
</ul>
<p>
-To use Push features, you must <a href="https://developer.tizen.org/development/tutorials/web-application/tizen-features/messaging/push#Registering">register to the Push service</a>.
+For more information on the Push features, see <a href="https://developer.tizen.org/development/tutorials/web-application/tizen-features/messaging/push#Registering">Push Guide</a>.
</p>
<p>
-For more information on the Push features, see <a href="https://developer.tizen.org/development/guides/web-application/tizen-features/messaging/push">Push Guide</a>.
+To use Push features the application needs the permission to access the Tizen Push servers.
</p>
+ <p>
+<b>Service Limitation:</b> </p>
+ <ul>
+ <li>
+Size of a push message is limited: <em>alertMessage</em> up to 127 bytes, and <em>appData</em> (payload data) less than 1 KB. </li>
+ <li>
+Push service does not guarantee delivery and order of push messages. </li>
+ </ul>
</div>
<p><span class="version">
Since: </span>
</p>
<h2>Table of Contents</h2>
<ul class="toc">
-<li>1. <a href="#typedefs-section">Type Definitions</a><ul class="toc"><li>1.1. <a href="#PushRegistrationId">PushRegistrationId</a>
-</li></ul>
+<li>1. <a href="#typedefs-section">Type Definitions</a><ul class="toc">
+<li>
+ 1.1. <a href="#PushRegistrationId">PushRegistrationId</a>
+</li>
+<li>
+ 1.2. <a href="#PushRegistrationState">PushRegistrationState</a>
+</li>
+</ul>
</li>
<li>2. <a href="#interfaces-section">Interfaces</a><ul class="toc">
<li>2.1. <a href="#PushManagerObject">PushManagerObject</a>
</li>
<li>2.4. <a href="#PushRegisterSuccessCallback">PushRegisterSuccessCallback</a>
</li>
-<li>2.5. <a href="#PushNotificationCallback">PushNotificationCallback</a>
+<li>2.5. <a href="#PushRegistrationStateChangeCallback">PushRegistrationStateChangeCallback</a>
+</li>
+<li>2.6. <a href="#PushNotificationCallback">PushNotificationCallback</a>
</li>
</ul>
</li>
<div>void <a href="#PushManager::register">register</a> (<a href="#PushRegisterSuccessCallback">PushRegisterSuccessCallback</a> successCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback)</div>
<div class="deprecated">void <a href="#PushManager::unregisterService">unregisterService</a> (optional <a href="tizen.html#SuccessCallback">SuccessCallback</a>? successCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback)</div>
<div>void <a href="#PushManager::unregister">unregister</a> (optional <a href="tizen.html#SuccessCallback">SuccessCallback</a>? successCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback)</div>
-<div>void <a href="#PushManager::connectService">connectService</a> (<a href="#PushNotificationCallback">PushNotificationCallback</a> notificationCallback)</div>
-<div>void <a href="#PushManager::disconnectService">disconnectService</a> ()</div>
+<div class="deprecated">void <a href="#PushManager::connectService">connectService</a> (<a href="#PushNotificationCallback">PushNotificationCallback</a> notificationCallback)</div>
+<div>void <a href="#PushManager::connect">connect</a> (<a href="#PushRegistrationStateChangeCallback">PushRegistrationStateChangeCallback</a> stateChangeCallback, <a href="#PushNotificationCallback">PushNotificationCallback</a> notificationCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback)</div>
+<div class="deprecated">void <a href="#PushManager::disconnectService">disconnectService</a> ()</div>
+<div>void <a href="#PushManager::disconnect">disconnect</a> ()</div>
<div>
<a href="#PushRegistrationId">PushRegistrationId</a> <a href="#PushManager::getRegistrationId">getRegistrationId</a> ()</div>
<div>void <a href="#PushManager::getUnreadNotifications">getUnreadNotifications</a> ()</div>
<td><div>void <a href="#PushRegisterSuccessCallback::onsuccess">onsuccess</a> (<a href="#PushRegistrationId">PushRegistrationId</a> id)</div></td>
</tr>
<tr>
+<td><a href="#PushRegistrationStateChangeCallback">PushRegistrationStateChangeCallback</a></td>
+<td><div>void <a href="#PushRegistrationStateChangeCallback::onsuccess">onsuccess</a> (<a href="#PushRegistrationState">PushRegistrationState</a> state)</div></td>
+</tr>
+<tr>
<td><a href="#PushNotificationCallback">PushNotificationCallback</a></td>
<td><div>void <a href="#PushNotificationCallback::onsuccess">onsuccess</a> (<a href="#PushMessage">PushMessage</a> message)</div></td>
</tr>
2.1
</p>
</div>
+<div class="enum" id="PushRegistrationState">
+<a class="backward-compatibility-anchor" name="::Push::PushRegistrationState"></a><h3>1.2. PushRegistrationState</h3>
+<div class="brief">
+ A push registration state.
+ </div>
+<pre class="webidl prettyprint"> enum PushRegistrationState {"REGISTERED", "UNREGISTERED"};</pre>
+<p><span class="version">
+ Since: </span>
+ 3.0
+ </p>
+<div class="description">
+ <ul>
+ <li>
+REGISTERED - The application is registered to the push server. </li>
+ <li>
+UNREGISTERED - The application is not registered to the push server. </li>
+ </ul>
+ </div>
+</div>
</div>
<div class="interfaces" id="interfaces-section">
<h2>2. Interfaces</h2>
optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
void unregister(optional <a href="tizen.html#SuccessCallback">SuccessCallback</a>? successCallback,
- optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
void connectService(<a href="#PushNotificationCallback">PushNotificationCallback</a> notificationCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+ void connect(<a href="#PushRegistrationStateChangeCallback">PushRegistrationStateChangeCallback</a> stateChangeCallback,
+ <a href="#PushNotificationCallback">PushNotificationCallback</a> notificationCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
void disconnectService() raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+ void disconnect() raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
<a href="#PushRegistrationId">PushRegistrationId</a> getRegistrationId() raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
void getUnreadNotifications() raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
http://tizen.org/privilege/push
</p>
<p><span class="remark"> Remark : </span>
- In order to use the push messaging service, see <a href="https://developer.tizen.org/development/guides/native-application/messaging/push">Push Messaging Guide</a>.
+ In order to use the push messaging service, see <a href="https://developer.tizen.org/development/guides/native-application/messaging/push">Push Guide</a>.
</p>
<div class="parameters">
<p><span class="param">Parameters:</span></p>
/* Defines the error callback */
function errorCallback(response)
{
- console.log('The following error occurred: ' + response.name);
+ console.log('The following error occurred: ' + response.name);
}
/* Defines the registration success callback */
</p>
<ul>
<li>
+TimeoutError - If the operation timed out. </li>
+ <li>
AbortError - If the operation cannot be finished properly. </li>
</ul>
</div>
+<div class="description">
+ <p>
+The <em>connect()</em> method must be called before calling the <em>register()</em> method.
+ </p>
+ </div>
<p><span class="privilegelevel">
Privilege level: </span>
public
Privilege: </span>
http://tizen.org/privilege/push
</p>
+<p><span class="remark"> Remark : </span>
+ In order to use the push messaging service, see <a href="https://developer.tizen.org/development/guides/native-application/messaging/push">Push Guide</a>.
+ </p>
<div class="parameters">
<p><span class="param">Parameters:</span></p>
<ul>
<li class="param">
<span class="name">successCallback</span>:
- The method to be called when the registration request succeeds.
+ The callback to be called when the registration request succeeds.
</li>
<li class="param">
<span class="name">errorCallback</span><span class="optional"> [optional]</span><span class="optional"> [nullable]</span>:
- The method to be called when the registration request fails.
+ The callback to be called when the registration request fails.
</li>
</ul>
</div>
<li class="list"><p>
with error type SecurityError, if the application does not have the privilege to call this method.
</p></li>
+<li class="list"><p>
+ with error type InvalidStateError, if the application is not connected to the push service.
+ </p></li>
+<li class="list"><p>
+ with error type AbortError, if the operation cannot be finished properly.
+ </p></li>
</ul>
</li></ul>
</div>
/* Defines the error callback */
function errorCallback(response)
{
- console.log("The following error occurred: " + response.name);
+ console.log("The following error occurred: " + response.name);
}
/* Defines the registration success callback */
console.log("Registration succeeded with id: " + id);
}
-/* Requests application registration */
-tizen.push.register(registerSuccessCallback, errorCallback);
+/* 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);
</pre>
</div>
<div class="output">
-<span class="title"><p>Output example:</p></span><pre> Registration succeeded with id: 04a150867a50f48cb79695ac732cbe550b4a6782fffd23cbc14ba8dd5c5ab0025dad29a3e4ef5de8849b95b726bea7a6395c
+<span class="title"><p>Output example:</p></span><pre> The state is changed to: UNREGISTERED
+ Registration succeeded with id: 04a150867a50f48cb79695ac732cbe550b4a6782fffd23cbc14ba8dd5c5ab0025dad29a3e4ef5de8849b95b726bea7a6395c
+ The state is changed to: REGISTERED
</pre>
</div>
</dd>
/* Defines the error callback */
function errorCallback(response)
{
- console.log('The following error occurred: ' + response.name);
+ console.log('The following error occurred: ' + response.name);
}
/* Defines the unregistration success callback */
</p>
<ul>
<li>
+TimeoutError - If the operation timed out. </li>
+ <li>
AbortError - If the operation cannot be finished properly. </li>
</ul>
</div>
<ul>
<li class="param">
<span class="name">successCallback</span><span class="optional"> [optional]</span><span class="optional"> [nullable]</span>:
- The method to be called when the unregistration request succeeds.
+ The callback to be called when the unregistration request succeeds.
</li>
<li class="param">
<span class="name">errorCallback</span><span class="optional"> [optional]</span><span class="optional"> [nullable]</span>:
- The method to be called when the unregistration request fails.
+ The callback to be called when the unregistration request fails.
</li>
</ul>
</div>
<li class="list"><p>
with error type SecurityError, if the application does not have the privilege to call this method.
</p></li>
+<li class="list"><p>
+ with error type InvalidStateError, if the application is not connected to the push service.
+ </p></li>
+<li class="list"><p>
+ with error type AbortError, if the operation cannot be finished properly.
+ </p></li>
</ul>
</li></ul>
</div>
<div class="example">
<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint">
+/* 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);
+ console.log("The following error occurred: " + response.name);
}
/* Defines the unregistration success callback */
</pre>
</div>
</dd>
-<dt class="method" id="PushManager::connectService">
+<dt class="deprecated method" id="PushManager::connectService">
<a class="backward-compatibility-anchor" name="::Push::PushManager::connectService"></a><code><b><span class="methodName">connectService</span></b></code>
</dt>
-<dd>
+<dd class="deprecated">
<div class="brief">
Connects to the push service and receives push notifications.
</div>
+<p class="deprecated"><b>Deprecated.</b>
+ This function has been deprecated since 3.0. Use the <a href="push.html#PushManager::connect">connect()</a> function instead.
+ </p>
<div class="synopsis"><pre class="signature prettyprint">void connectService(<a href="#PushNotificationCallback">PushNotificationCallback</a> notificationCallback);
</pre></div>
<p><span class="version">
</p>
<p><span class="remark"> Remark : </span>
If the application calling the <em>connectService()</em> method has not been registered to the Tizen push server,
-the <em>register()</em> method must be called before calling the <em>connectService()</em> method.
+the <em>registerService()</em> method must be called before calling the <em>connectService()</em> method.
</p>
<div class="parameters">
<p><span class="param">Parameters:</span></p>
</div>
<div class="example">
<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint">
-/* Defines the registration error callback */
+/* 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);
+ 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);
+</pre>
+</div>
+</dd>
+<dt class="method" id="PushManager::connect">
+<a class="backward-compatibility-anchor" name="::Push::PushManager::connect"></a><code><b><span class="methodName">connect</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Connects to the push service and gets state change events and push notifications.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">void connect(<a href="#PushRegistrationStateChangeCallback">PushRegistrationStateChangeCallback</a> stateChangeCallback, <a href="#PushNotificationCallback">PushNotificationCallback</a> notificationCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 3.0
+ </p>
+<div class="description">
+ <p>
+The <em>ErrorCallback()</em> is launched with these error types:
+ </p>
+ <ul>
+ <li>
+AbortError - If the operation cannot be finished properly. </li>
+ </ul>
+ </div>
+<p><span class="privilegelevel">
+ Privilege level: </span>
+ public
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/push
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">stateChangeCallback</span>:
+ 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.
+ </li>
+ <li class="param">
+<span class="name">notificationCallback</span>:
+ The callback to be called when the notification message arrives.
+ </li>
+ <li class="param">
+<span class="name">errorCallback</span><span class="optional"> [optional]</span><span class="optional"> [nullable]</span>:
+ The callback to be called when the connect request fails.
+ </li>
+ </ul>
+</div>
+<div class="exceptionlist">
+<p><span class="except">Exceptions:</span></p>
+ <ul class="exception"><li>WebAPIException<ul>
+<li class="list"><p>
+ with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
+ </p></li>
+<li class="list"><p>
+ with error type SecurityError, if the application does not have the privilege to call this method.
+ </p></li>
+<li class="list"><p>
+ with error type AbortError, if the operation cannot be finished properly.
+ </p></li>
+</ul>
+</li></ul>
+ </div>
+<div class="example">
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint">
+/* Defines the state change callback */
+function stateChangeCallback(state)
+{
+ console.log("The state is changed to: " + state);
}
-/* Requests application registration */
-tizen.push.register(registerSuccessCallback, errorCallback);
+/* Defines the notification callback */
+function notificationCallback(notification)
+{
+ console.log("A notification arrives.");
+}
-/* Defines the connect success callback */
-function notificationCallback(noti)
+/* Defines the error callback */
+function errorCallback(error)
{
- console.log("Notification received with alert message: " + noti.alertMessage);
+ console.log("The following error occurred: " + error.name);
}
/* Requests for push service connection */
-tizen.push.connectService(notificationCallback);
+tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
</pre>
</div>
+<div class="output">
+<span class="title"><p>Output example:</p></span><pre> The state is changed to: UNREGISTERED
+ </pre>
+</div>
</dd>
-<dt class="method" id="PushManager::disconnectService">
+<dt class="deprecated method" id="PushManager::disconnectService">
<a class="backward-compatibility-anchor" name="::Push::PushManager::disconnectService"></a><code><b><span class="methodName">disconnectService</span></b></code>
</dt>
-<dd>
+<dd class="deprecated">
<div class="brief">
Disconnects the push service and stops receiving push notifications.
</div>
+<p class="deprecated"><b>Deprecated.</b>
+ This function has been deprecated since 3.0. Use the <a href="push.html#PushManager::disconnect">disconnect()</a> function instead.
+ </p>
<div class="synopsis"><pre class="signature prettyprint">void disconnectService();
</pre></div>
<p><span class="version">
with error type SecurityError, if the application does not have the privilege to call this method.
</p></li>
<li class="list"><p>
- with error type UnknownError, if any other error occurs.
+ with error type AbortError, if the operation cannot be finished properly.
</p></li>
</ul>
</li></ul>
</pre>
</div>
</dd>
+<dt class="method" id="PushManager::disconnect">
+<a class="backward-compatibility-anchor" name="::Push::PushManager::disconnect"></a><code><b><span class="methodName">disconnect</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Disconnects the push service and stops receiving push notifications.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">void disconnect();
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 3.0
+ </p>
+<p><span class="privilegelevel">
+ Privilege level: </span>
+ public
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/push
+ </p>
+<div class="exceptionlist">
+<p><span class="except">Exceptions:</span></p>
+ <ul class="exception"><li>WebAPIException<ul>
+<li class="list"><p>
+ with error type SecurityError, if the application does not have the privilege to call this method.
+ </p></li>
+<li class="list"><p>
+ with error type UnknownError, if any other error occurs.
+ </p></li>
+</ul>
+</li></ul>
+ </div>
+<div class="example">
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint">
+/* Requests disconnection */
+tizen.push.disconnect();
+</pre>
+</div>
+</dd>
<dt class="method" id="PushManager::getRegistrationId">
<a class="backward-compatibility-anchor" name="::Push::PushManager::getRegistrationId"></a><code><b><span class="methodName">getRegistrationId</span></b></code>
</dt>
}
</pre>
</div>
+<div class="example">
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint">
+/* 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);
+</pre>
+</div>
+<div class="output">
+<span class="title"><p>Output example:</p></span><pre> The state is changed to: UNREGISTERED
+ The registration ID: 04a150867a50f48cb79695ac732cbe550b4a6782fffd23cbc14ba8dd5c5ab0025dad29a3e4ef5de8849b95b726bea7a6395c
+ </pre>
+</div>
</dd>
<dt class="method" id="PushManager::getUnreadNotifications">
<a class="backward-compatibility-anchor" name="::Push::PushManager::getUnreadNotifications"></a><code><b><span class="methodName">getUnreadNotifications</span></b></code>
tizen.push.getUnreadNotifications();
</pre>
</div>
+<div class="example">
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint">
+/* 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);
+</pre>
+</div>
+<div class="output">
+<span class="title"><p>Output example:</p></span><pre> The state is changed to: REGISTERED
+ </pre>
+</div>
</dd>
<dt class="method" id="PushManager::getPushMessage">
<a class="backward-compatibility-anchor" name="::Push::PushManager::getPushMessage"></a><code><b><span class="methodName">getPushMessage</span></b></code>
<div class="description">
<p>
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 <a href="push.html#Push%20Manager::register">register()</a> and
-<a href="push.html#Push%20Manager::connectService">connectService()</a> functions.
+Therefore, you can get push messages without calling the <a href="push.html#Push%20Manager::connect">connect()</a> function.
</p>
<p>
If the application was not launched by the push service, this method returns <em>null</em>.
</dl>
</div>
</div>
+<div class="interface" id="PushRegistrationStateChangeCallback">
+<a class="backward-compatibility-anchor" name="::Push::PushRegistrationStateChangeCallback"></a><h3>2.5. PushRegistrationStateChangeCallback</h3>
+<div class="brief">
+ The PushRegistrationStateChangeCallback interface specifies the state change callback for the state change event.
+ </div>
+<pre class="webidl prettyprint"> [Callback=FunctionOnly, NoInterfaceObject]
+ interface PushRegistrationStateChangeCallback {
+ void onsuccess(<a href="#PushRegistrationState">PushRegistrationState</a> state);
+ };</pre>
+<p><span class="version">
+ Since: </span>
+ 3.0
+ </p>
+<div class="description">
+ <p>
+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.
+ </p>
+ </div>
+<div class="methods">
+<h4>Methods</h4>
+<dl>
+<dt class="method" id="PushRegistrationStateChangeCallback::onsuccess">
+<a class="backward-compatibility-anchor" name="::Push::PushRegistrationStateChangeCallback::onsuccess"></a><code><b><span class="methodName">onsuccess</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Called when the state of push registration is changed.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">void onsuccess(<a href="#PushRegistrationState">PushRegistrationState</a> state);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 3.0
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">state</span>:
+ The state of push registration.
+ </li>
+ </ul>
+</div>
+</dd>
+</dl>
+</div>
+</div>
<div class="interface" id="PushNotificationCallback">
-<a class="backward-compatibility-anchor" name="::Push::PushNotificationCallback"></a><h3>2.5. PushNotificationCallback</h3>
+<a class="backward-compatibility-anchor" name="::Push::PushNotificationCallback"></a><h3>2.6. PushNotificationCallback</h3>
<div class="brief">
The PushNotificationCallback interface specifies the notification callback for the received push notification message.
</div>
<li class="feature">http://tizen.org/feature/network.push</li>
</div>
<p></p>
- For more information, see <a href="https://developer.tizen.org/development/getting-started/web-application/understanding-tizen-programming/application-filtering">Application Filtering</a>.
+ For more information, see <a href="https://developer.tizen.org/development/getting-started/web-application/understanding-tizen-programming/application-filtering">Application Filtering.</a>
</div>
<h2 id="full-webidl">4. Full WebIDL</h2>
<pre class="webidl prettyprint">module Push {
+
typedef DOMString PushRegistrationId;
+ enum PushRegistrationState {"REGISTERED", "UNREGISTERED"};
+
[NoInterfaceObject] interface PushManagerObject {
readonly attribute <a href="#PushManager">PushManager</a> push;
};
optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
void unregister(optional <a href="tizen.html#SuccessCallback">SuccessCallback</a>? successCallback,
- optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
void connectService(<a href="#PushNotificationCallback">PushNotificationCallback</a> notificationCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+ void connect(<a href="#PushRegistrationStateChangeCallback">PushRegistrationStateChangeCallback</a> stateChangeCallback,
+ <a href="#PushNotificationCallback">PushNotificationCallback</a> notificationCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
void disconnectService() raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+ void disconnect() raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
<a href="#PushRegistrationId">PushRegistrationId</a> getRegistrationId() raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
void getUnreadNotifications() raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
};
[Callback=FunctionOnly, NoInterfaceObject]
+ interface PushRegistrationStateChangeCallback {
+ void onsuccess(<a href="#PushRegistrationState">PushRegistrationState</a> state);
+ };
+
+ [Callback=FunctionOnly, NoInterfaceObject]
interface PushNotificationCallback {
void onsuccess(<a href="#PushMessage">PushMessage</a> message);
};
projects / sdk / online-doc.git / commitdiff