<li>Package ID
<p>When you create a project in the Tizen Studio, you are given the package ID (randomly generated by the Tizen Studio or entered by yourself). The Tizen push server identifies your applications using the package ID.</p></li>
<li id="permission" name="permission">Permission to Tizen push servers
-<p>To use the push messaging service, the application needs the permission to access the Tizen push server. Request the permission from the Tizen push service team by <a href="mailto:push.tizen@samsung.com">email</a>, including the following information. When the team approves the request, you receive a push app ID corresponding to your package ID.</p>
-<p>By sending the application, you agree to the <a href="https://www.tizen.org/about/terms-service" target="_blank">Terms of Service</a> and <a href="https://www.tizen.org/about/privacy-policy" target="_blank">Privacy Policy</a>.</p>
-</li>
-</ol>
+<p>To use the push messaging service, the application needs the permission to access the Tizen push server. Request the permission from the Tizen push service team by <a href="mailto:push.tizen@samsung.com">email</a>. When the team approves the request, you receive a push app ID corresponding to your package ID.</p>
+<p>By sending the request, you agree to the <a href="https://www.tizen.org/about/terms-service" target="_blank">Terms of Service</a> and <a href="https://www.tizen.org/about/privacy-policy" target="_blank">Privacy Policy</a>. The TPS (transactions per second) in the push messaging service is fixed as 150.</p>
+<p>To request the permission for a new application, include the following information in your email.</p>
<table id="request_form">
-<caption>Table: Request form details</caption>
+<caption>Table: Request form details for a new application</caption>
<tbody>
<tr>
<th colspan="2">Developer information</th>
</tr>
<tr>
<td>Email address</td>
- <td>Your email address to receive the approval response.</td>
+ <td>Your email address to receive the approval response</td>
</tr>
<tr>
<td>Last name</td>
- <td>Your last name.</td>
+ <td>Your last name</td>
</tr>
<tr>
<td>First name</td>
- <td>Your first name.</td>
+ <td>Your first name</td>
</tr>
<tr>
<td>Country</td>
- <td>Your country of residence.</td>
+ <td>Your country of residence</td>
</tr>
<tr>
<th colspan="2">Application information</th>
</tr>
<tr>
<td>Package ID</td>
- <td>The ID of the application package that uses the push messaging service. The package ID can be obtained from the application manifest file in the Tizen Studio.</td>
+ <td>ID of the application package that uses the push messaging service. The package ID can be obtained from the application manifest file in the Tizen Studio.</td>
</tr>
<tr>
<td>Application name</td>
- <td>Name of the application that uses the push service.</td>
+ <td>Name of the application that uses the push service</td>
</tr>
<tr>
<td>Application type</td>
- <td>Native application or Web application.</td>
+ <td>Tizen native application or Tizen Web application</td>
</tr>
<tr>
<td>Testing purpose</td>
- <td> Yes or no. If you request the service for testing purposes only, the duration of the push service is limited to 3 weeks.</td>
+ <td>Yes or no. If you request the service for testing purposes only, the duration of the push service is limited to 3 weeks.</td>
</tr>
<tr>
- <td> Purpose of the push notification usage</td>
- <td> Description of how you plan to use the push service, including the situations in which you want to use it.</td>
+ <td>Purpose of the push notification usage</td>
+ <td>Description of how you plan to use the push service, including the situations in which you want to use it</td>
</tr>
<tr>
- <td> Application launch date</td>
- <td> Application launch date in the YYYY/MM/DD format. For example: 2014/08/01.</td>
+ <td>Application launch date</td>
+ <td>Application launch date in the YYYY/MM/DD format, for example: 2014/08/01</td>
</tr>
<tr>
<td>Service area/country</td>
- <td>Service area, such as Asia, Africa, America, Europe, or the country where the application is used.</td>
+ <td>Service area or the country where the application is used. You can use <strong>Global</strong>, or specify a more limited area (<strong>Africa</strong>, <strong>America</strong>, <strong>Asia</strong>, <strong>Europe</strong>, <strong>Oceania</strong>), or a specific country.</td>
</tr>
<tr>
<td>Daily push requests</td>
- <td>Estimated number of daily notifications.</td>
+ <td>Estimated number of daily notifications</td>
</tr>
- <tr>
- <td> Transactions per second</td>
- <td> Estimated peak number of transactions per second (the recommendation is below 100).</td>
+ <tr>
+ <td>Push notification payload size</td>
+ <td>1 or 2 kb</td>
+ </tr>
+</tbody>
+</table>
+
+<p>To extend the expiration date or change the quota for an application that already has the permission to use the push messaging service, include the following information in your email.</p>
+<table id="request_form_extend">
+<caption>Table: Request form details to modify the access permissions of an application</caption>
+<tbody>
+ <tr>
+ <th colspan="2">Application information for extending the expiration date</th>
+ </tr>
+ <tr>
+ <td>Push app ID</td>
+ <td>Push app ID you received when you originally requested permission for a new application</td>
+ </tr>
+ <tr>
+ <td>Expiration date</td>
+ <td>Application launch date in the YYYY/MM/DD format, for example: 2017/08/01</td>
+ </tr>
+ <tr>
+ <th colspan="2">Application information for changing the quota</th>
+ </tr>
+ <tr>
+ <td>Push app ID</td>
+ <td>Push app ID you received when you originally requested permission for a new application</td>
+ </tr>
+ <tr>
+ <td>Daily push requests</td>
+ <td>Estimated number of daily notifications</td>
</tr>
</tbody>
</table>
</li>
+</ol>
+</li>
<li><p>To use the functions and data types of the Push API, include the <span style="font-family: Courier New,Courier,monospace;"><push-service.h></span> header file to your application:</p>
<p>The following example shows a sample push notification:</p>
<ul>
-<li>URI: See the <a href="push_server_n.htm#send_server">Push server URL table</a>.</li>
+<li>URI: See the <a href="push_server_n.htm#send_server">Push RQM (Request Manager) server URLs table</a>.</li>
<li>Method: HTTP POST</li>
<li>Header:
<pre class="prettyprint">
<li>Prepare the appID, appSecret, regID, and requestID:
<ul>
<li>The appID and appSecret values are from the email that you received when requesting <a href="#permission">permission to Tizen push servers</a>.</li>
-<li>The regID value is the one that the application server received from your application installed in a Tizen device. Depending on the regID value, the URI of the server to which your application server sends the notification varies.
-<p>Since Tizen 3.0, the format of the regID is changed to support multiple users. A hyphen and the application's UID are added at the end of the regID.</p>
-</li>
+<li>The regID value is the one that the application server received from your application installed in a Tizen device. Depending on the regID value, the URI of the server to which your application server sends the notification varies.</li>
<li>The requestID value is used to identify the notification in the push server. When your application server sends notifications using the same requestID value, the last notification overwrites all the previous notifications that are not delivered yet.</li>
</ul>
</li>
</script>
</body>
-</html>
\ No newline at end of file
+</html>
<p>The request manager (RQM) servers collect your push notifications before sending them to the applications. The RQM server must be chosen based on the first 2 digits of the registration ID.</p>
<table>
-<caption>Table: RQM servers</caption>
+<caption>Table: Push RQM server URLs</caption>
<tbody>
<tr>
<th>Prefix of the <span style="font-family: Courier New,Courier,monospace;">regId</span></th>
<p>For example, if the registration ID of the application that you want to send a notification to begins with 04, the URL of the RQM server must be <span style="font-family: Courier New,Courier,monospace;">https://apnortheast.push.samsungosp.com:8090/spp/pns/api/push</span>.</p>
</li>
+<li>Determine the type of push notification.
+<p>Since Tizen 3.0, you can determine the notification type. You can send a notification either to notify a user about urgent information or to deliver data to the application for update:</p>
+<ul>
+<li>If you have an urgent message or data for the user, fill the message field with a proper action value:
+<pre class="prettyprint">
+{
+ "messages":
+ [{
+ ...
+ "message": "action=ALERT&badgeOption=INCREASE&badgeNumber=1&alertMessage=Hi",
+ "appData": "{id:asdf&passwd:1234}",
+ ...
+ ]}
+}
+</pre>
+</li>
+<li>If you have data to send to the application but no need to notify the user, use the action field on the same level as the message field, instead of within the message field, and do not include the message field itself. In this case, the notification is delivered with the best effort.
+<pre class="prettyprint">
+{
+ "messages":
+ [{
+ ...
+ "action": "backgroundLaunch",
+ "appData": "{id:asdf&passwd:1234}",
+ ...
+ ]}
+}
+</pre>
+</li></ul>
+</li>
+
+
<li>Create the notification message.
<p>A message is one of the fields that constitute a notification. The message field contains not only the message to show in the quick panel on the device, but also the behaviors that the device must take when receiving the notification. The message field is a string that consists of key-value pairs. The available pair options are given in the following table.</p>
</pre>
<p>The message field takes effect only when the application is not running (more precisely, when the application is not connected to the push service). If a notification with the above message field arrives at the device where the application is running, the push service delivers the notification directly to the application. It does not show the "Hi" message in the quick panel or increase the badge count.</p>
+
+<p>Since Tizen 3.0, the <span style="font-family: Courier New,Courier,monospace;">BACKGROUNDLAUNCH</span> option is supported. When you send a notification to the device with the <span style="font-family: Courier New,Courier,monospace;">BACKGROUNDLAUNCH</span> action value, the push service launches the application in the background (if it is not already running), and delivers the appData field to the application. The user cannot see that a notification is received, but they find out when they use the application the next time.</p>
+<table class="note">
+ <tbody>
+ <tr>
+ <th class="note">Note</th>
+ </tr>
+ <tr>
+ <td class="note">In case of the <span style="font-family: Courier New,Courier,monospace;">BACKGROUNDLAUNCH</span> notification, the <span style="font-family: Courier New,Courier,monospace;">app_create()</span> and <span style="font-family: Courier New,Courier,monospace;">app_control()</span> life-cycle callbacks are called, but the <span style="font-family: Courier New,Courier,monospace;">app_resume()</span> callback is not called. However, the next time the user runs the application, the <span style="font-family: Courier New,Courier,monospace;">app_resume()</span> callback is invoked normally. For more information on the life-cycle, see the <a href="../../../../org.tizen.guides/html/native/app_management/applications_n.htm">Applications</a> guide.</td>
+ </tr>
+ </tbody>
+</table>
</li>
<li>Use the Rest APIs for sending push notifications.
<li>Default: <span style="font-family: Courier New,Courier,monospace;">NULL</span></li></ul></td>
</tr>
<tr>
+ <td><span style="font-family: Courier New,Courier,monospace;">action</span><p>(since Tizen 3.0)</p></td>
+ <td>This message is delivered along with another urgent message, when the action value is <span style="font-family: Courier New,Courier,monospace;">"backgroundLaunch"</span> and message field is <span style="font-family: Courier New,Courier,monospace;">NULL</span>.</td>
+ <td>
+<ul><li>Optional</li>
+ <li>Type: string</li>
+ <li>Default: <span style="font-family: Courier New,Courier,monospace;">NULL</span></li></ul>
+</td>
+</tr>
+<tr>
<td><span style="font-family: Courier New,Courier,monospace;">message</span></td>
<td>The message the sender wants to deliver. It can be a multibyte character.
<p>The message goes from an application server through the push server and push service to the application, which can handle the message.</p>
<h2 id="decorate_noti" name="decorate_noti">Decorating Push Notifications</h2>
-
<p>Since Tizen 3.0, you can decorate push notifications you send from the application server to Tizen devices. For example, you can add images and sounds to the notifications. The push service creates a notification using the resources from the application and notifies the user. You can compose the push message using a set of REST APIs.</p>
<p>To decorate push notifications, you have to understand the notification functions. In addition to the existing <span style="font-family: Courier New,Courier,monospace;">message</span> field, more fields are provided. For more details about the functions to use to create a notification, see the Notification API (in <a href="../../../../org.tizen.native.mobile.apireference/group__NOTIFICATION__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__NOTIFICATION__MODULE.html">wearable</a> applications). When you include a key and value in the message field, the push service creates a notification as the application creates a notification using the Notification API.</p>
<p>Prepare all the resource files under the <span style="font-family: Courier New,Courier,monospace;">/shared/res</span> folder in your application, and you can directly address the resource files. For example, <span style="font-family: Courier New,Courier,monospace;">imageTypeIcon=image.png</span> means that the <span style="font-family: Courier New,Courier,monospace;">/share/res/image.png</span> image is displayed as an icon in the notification panel. You can perform the same action by calling the <span style="font-family: Courier New,Courier,monospace;">notification_set_image(noti, NOTIFICATION_IMAGE_TYPE_ICON, "image.png")</span> function.</p>
<p>The following example shows the message field for an active notification with 3 buttons:</p>
<pre class="prettyprint">
-"message":"setAutoRemove=true
-&textTypeButton1=Connect&textTypeButton2=Hold&textTypeButton3=Cancel&
-eventTypeClickOnButton1=test,connect& eventTypeClickOnButton2=test,hold&
+"message":"setAutoRemove=true&
+textTypeButton1=Connect&textTypeButton2=Hold&textTypeButton3=Cancel&
+eventTypeClickOnButton1=test,connect& eventTypeClickOnButton2=test,hold&
eventTypeClickOnButton3=test,cancel& eventTypeClickOnIcon=test,icon&
eventTypeClickOnThumbnail=test,thumbnail&badgeOption=INCREASE&badgeNumber=1&action=ALERT&
alertMessage=Hi& textTypeTitle=Active Notification Title&textTypeContent=Hi&
imageTypeIcon=icon.png&imageTypeIconForIndicator=indicator.png&imageTypeThumbnail=thumbnail.png&
imageTypeIconSub=sub.png &imageTypeBackground=background.png& soundTypeUserData=test.wav&
-setDisplayApplist=notificationTray|ticker|lock|indicator|active|all&lyNotiEventSingle=true&
-textTypeContentForDisplayOptionIsOff=contentoptionoff& textTypeEventCount=34&textTypeInfo1=Test
-notification&setTime=true&setTimeToText=true\"
+setDisplayApplist=notificationTray|ticker|lock|indicator|active|all&lyNotiEventSingle=true&
+textTypeContentForDisplayOptionIsOff=contentoptionoff& textTypeEventCount=34&textTypeInfo1=Test
+notification&setTime=true&setTimeToText=true"
</pre>
<p>The following figure shows a decorated push notification.</p>
<p class="figure">Figure: Decorated notification</p>
<p align="center"><img alt="Decorated notification" src="../../images/push_active_notification.png"/></p>
+<p>If the user presses any of the 3 buttons, the <span style="font-family: Courier New,Courier,monospace;">app_control()</span> callback of your application is called. Use the following code for further actions:</p>
+<pre class="prettyprint">
+#define KEY_FROM_ACTIVE_NOTICATION "test"
+
+static void
+app_control(app_control_h app_control, void *data)
+{
+ char *value = NULL;
+ app_control_get_extra_data(app_control, KEY_FROM_ACTIVE_NOTICATION, &value);
+ if (value) {
+ if (!strcmp(value, "connect"))
+ /* Add code here to react to Connect button press */
+ else if (!strcmp(value, "hold"))
+ /* Add code here to react to Hold button press */
+ else if (!strcmp(value, "cancel"))
+ /* Add code here to react to Cancel button press */
+ }
+ app_control_get_extra_data(app_control, APP_CONTROL_DATA_PUSH_LAUNCH_TYPE, &value);
+ if (value) {
+ if (!strcmp(value, EXTRA_DATA_FROM_NOTIFICATION))
+ /* Add code here to react to arriving push messages */
+ else if (!strcmp(value, EXTRA_DATA_FROM_REGISTRATION_CHANGE))
+ /* Add code here to react to registration state changes */
+ }
+ /* Add code here to react to registration state changes */
+}
+</pre>
+<p>Since Tizen 3.0, you can use a notification template to reuse well-decorated notification content without having to define it from scratch each time. When you want to use the same notification multiple times, you can make and save a template for it. Use the <span style="font-family: Courier New,Courier,monospace;">notification_save_as_template()</span> function to save the notification handle. For more information on the function, see the Notification API (in <a href="../../../../org.tizen.native.mobile.apireference/group__NOTIFICATION__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__NOTIFICATION__MODULE.html">wearable</a> applications).</p>
+<p>Once you save a notification template with a specific name, you can use the <span style="font-family: Courier New,Courier,monospace;">template</span> key in the message field to load the template when you send a notification.</p>
+<table>
+<caption>Table: Notification template key-value pair</caption>
+<tbody>
+<tr>
+ <th>Key</th>
+ <th>Value</th>
+ <th>Description</th>
+</tr>
+<tr>
+<td><span style="font-family: Courier New,Courier,monospace;">template</span></td>
+ <td>string</td>
+ <td>Create a notification handle from the received template name, if a saved notification template exists.</td>
+</tr>
+</tbody>
+</table>
+<p>The following example shows how to use the <span style="font-family: Courier New,Courier,monospace;">template</span> key in the message field:</p>
+<pre class="prettyprint">
+"message":"template=noti_template"
+</pre>
+
<h2 id="error_codes" name="error_codes">Handling Error Codes</h2>
<p>If sending a push notification request fails for some reason, the response message contains an error code. Use the following table to identify the reason for the failure and take appropriate action.</p>
</script>
</body>
-</html>
\ No newline at end of file
+</html>
projects / sdk / online-doc.git / commitdiff