From: Younho Park Date: Thu, 24 Nov 2016 04:44:20 +0000 (+0900) Subject: [Push] Added 3.0 features (Notification template & urgent push) X-Git-Tag: tizen_3.0/TD_SYNC/20161201~2^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F52%2F99752%2F2;p=sdk%2Fonline-doc.git [Push] Added 3.0 features (Notification template & urgent push) PS2: [LB] Reviewed Change-Id: I9553d885f966d33f91c57b5b1f501c8fc472ca4b Signed-off-by: Younho Park --- diff --git a/org.tizen.guides/html/native/messaging/push_n.htm b/org.tizen.guides/html/native/messaging/push_n.htm index a556d2b..9e3c453 100644 --- a/org.tizen.guides/html/native/messaging/push_n.htm +++ b/org.tizen.guides/html/native/messaging/push_n.htm @@ -129,75 +129,105 @@
  • Package ID

    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.

  • Permission to Tizen push servers -

    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 email, including the following information. When the team approves the request, you receive a push app ID corresponding to your package ID.

    -

    By sending the application, you agree to the Terms of Service and Privacy Policy.

    -
    • - +

    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 email. When the team approves the request, you receive a push app ID corresponding to your package ID.

    +

    By sending the request, you agree to the Terms of Service and Privacy Policy. The TPS (transactions per second) in the push messaging service is fixed as 150.

    +

    To request the permission for a new application, include the following information in your email.

    - + - + - + - + - + - + - + - + - + - - + + - - + + - + - + - - - + + + + + +
    Table: Request form detailsTable: Request form details for a new application
    Developer information
    Email addressYour email address to receive the approval response.Your email address to receive the approval response
    Last nameYour last name.Your last name
    First nameYour first name.Your first name
    CountryYour country of residence.Your country of residence
    Application information
    Package IDThe 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.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.
    Application nameName of the application that uses the push service.Name of the application that uses the push service
    Application typeNative application or Web application.Tizen native application or Tizen Web application
    Testing purpose Yes or no. If you request the service for testing purposes only, the duration of the push service is limited to 3 weeks.Yes or no. If you request the service for testing purposes only, the duration of the push service is limited to 3 weeks.
    Purpose of the push notification usage Description of how you plan to use the push service, including the situations in which you want to use it.Purpose of the push notification usageDescription of how you plan to use the push service, including the situations in which you want to use it
    Application launch date Application launch date in the YYYY/MM/DD format. For example: 2014/08/01.Application launch dateApplication launch date in the YYYY/MM/DD format, for example: 2014/08/01
    Service area/countryService area, such as Asia, Africa, America, Europe, or the country where the application is used.Service area or the country where the application is used. You can use Global, or specify a more limited area (Africa, America, Asia, Europe, Oceania), or a specific country.
    Daily push requestsEstimated number of daily notifications.Estimated number of daily notifications
    Transactions per second Estimated peak number of transactions per second (the recommendation is below 100).
    Push notification payload size1 or 2 kb
    + +

    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.

    + + + + + + + + + + + + + + + + + + + + + + + +
    Table: Request form details to modify the access permissions of an application
    Application information for extending the expiration date
    Push app IDPush app ID you received when you originally requested permission for a new application
    Expiration dateApplication launch date in the YYYY/MM/DD format, for example: 2017/08/01
    Application information for changing the quota
    Push app IDPush app ID you received when you originally requested permission for a new application
    Daily push requestsEstimated number of daily notifications
    + +

  • To use the functions and data types of the Push API, include the <push-service.h> header file to your application:

    @@ -563,7 +593,7 @@ push_service_deregister(push_conn, _dereg_result_cb, NULL);

    The following example shows a sample push notification:

      -
    • URI: See the Push server URL table.
      • +
    • URI: See the Push RQM (Request Manager) server URLs table.
    • Method: HTTP POST
    • Header: 
      @@ -588,9 +618,7 @@ appSecret: dYo/o/m11gmWmjs7+5f+2zLNVOc=
 
    • Prepare the appID, appSecret, regID, and requestID:
 
        
 
      • The appID and appSecret values are from the email that you received when requesting permission to Tizen push servers.
        •  
-
      • 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. 
-
        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.
        
-
        • 
+
      • 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.
        • 
 
      • 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.
        • 
 
      
 
      • 
@@ -832,4 +860,4 @@ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga
 
 
 
-
\ No newline at end of file
+
diff --git a/org.tizen.guides/html/native/messaging/push_server_n.htm b/org.tizen.guides/html/native/messaging/push_server_n.htm
index c10d60c..1d36fc6 100644
--- a/org.tizen.guides/html/native/messaging/push_server_n.htm
+++ b/org.tizen.guides/html/native/messaging/push_server_n.htm
@@ -66,7 +66,7 @@
 
      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.
      
 
 
-
+
@@ -139,6 +139,38 @@
 
      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 https://apnortheast.push.samsungosp.com:8090/spp/pns/api/push.
      
 
+
    • Determine the type of push notification.
+
      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:
       
+
        
+
      • If you have an urgent message or data for the user, fill the message field with a proper action value:
+
        +{
+    "messages":
+    [{
+        ...
+        "message": "action=ALERT&badgeOption=INCREASE&badgeNumber=1&alertMessage=Hi",
+        "appData": "{id:asdf&passwd:1234}",
+        ...
+    ]}
+}
+
        
+
        • 
+
      • 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.
+
        +{
+    "messages":
+    [{
+        ...
+        "action": "backgroundLaunch",
+        "appData": "{id:asdf&passwd:1234}",
+        ...
+    ]}
+}
+
        
+
      
+
      • 
+
+
 
    • Create the notification message.
 
      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.
      
 
@@ -186,6 +218,18 @@
 
 
 
      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.
      
+
+
      Since Tizen 3.0, the BACKGROUNDLAUNCH option is supported. When you send a notification to the device with the BACKGROUNDLAUNCH 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.
      
+
      • Table: RQM serversTable: Push RQM server URLs
 
 
      
  Prefix of the regId
 
      
+    
+        
+            
+        
+        
+            
+        
+    
+
      Note
      In case of the BACKGROUNDLAUNCH notification, the app_create() and app_control() life-cycle callbacks are called, but the app_resume() callback is not called. However, the next time the user runs the application, the app_resume() callback is invoked normally. For more information on the life-cycle, see the Applications guide.
    • Use the Rest APIs for sending push notifications. @@ -256,6 +300,15 @@
    • Default: NULL
    + action

    (since Tizen 3.0)

    + This message is delivered along with another urgent message, when the action value is "backgroundLaunch" and message field is NULL. + +
    • Optional
      • +
    • Type: string
      • +
    • Default: NULL
    + + + message The message the sender wants to deliver. It can be a multibyte character.

    The message goes from an application server through the push server and push service to the application, which can handle the message.

    @@ -620,7 +673,6 @@ appSecret: dYo/o/m11gmWmjs7+5f+2zLNVOc=

    Decorating Push Notifications

    -

    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.

    To decorate push notifications, you have to understand the notification functions. In addition to the existing message field, more fields are provided. For more details about the functions to use to create a notification, see the Notification API (in mobile and wearable 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.

    Prepare all the resource files under the /shared/res folder in your application, and you can directly address the resource files. For example, imageTypeIcon=image.png means that the /share/res/image.png image is displayed as an icon in the notification panel. You can perform the same action by calling the notification_set_image(noti, NOTIFICATION_IMAGE_TYPE_ICON, "image.png") function.

    @@ -908,17 +960,17 @@ appSecret: dYo/o/m11gmWmjs7+5f+2zLNVOc=

    The following example shows the message field for an active notification with 3 buttons:

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

    The following figure shows a decorated push notification.

    @@ -926,6 +978,55 @@ notification&setTime=true&setTimeToText=true\"

    Figure: Decorated notification

    Decorated notification

    +

    If the user presses any of the 3 buttons, the app_control() callback of your application is called. Use the following code for further actions:

    +
    +#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 */
+}
+
    +

    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 notification_save_as_template() function to save the notification handle. For more information on the function, see the Notification API (in mobile and wearable applications).

    +

    Once you save a notification template with a specific name, you can use the template key in the message field to load the template when you send a notification.

    + + + + + + + + + + + + + + +
    Table: Notification template key-value pair
    KeyValueDescription
    templatestringCreate a notification handle from the received template name, if a saved notification template exists.
    +

    The following example shows how to use the template key in the message field:

    +
    +"message":"template=noti_template"
+
    +

    Handling Error Codes

    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.

    @@ -1159,4 +1260,4 @@ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga - \ No newline at end of file +