Push Server

You can push events from an application server to your application on a Tizen device. If the message sending fails for any reason, an error code identifying the failure reason is returned. You can use the error code to determine how to handle the failure.

The Push API is optional for the Tizen Wearable profile, which means that it may not be supported on all wearable devices.

The main features of the Push API for the server developers include:

• Sending push notifications

  You can send push notifications from the application server to an application.

• Decorating push notifications

  You can add decorations to the push notifications in the quick panel.

Sending Push Notifications

You can send notifications to your applications installed on Tizen devices. The basics of sending push notifications are covered in the Push guide. This use case covers more advanced information, such as sending multiple notifications in one request and sending multicast notifications.

To send push notifications:

1. Determine the RQM server.

   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.

   Table: Push RQM server URLs

   Prefix of the regId	Region	URL
   00	US East	https://useast.push.samsungosp.com:8090/spp/pns/api/push
   02	Asia Pacific Southeast	https://apsoutheast.push.samsungosp.com:8090/spp/pns/api/push
   03	EU West	https://euwest.push.samsungosp.com:8090/spp/pns/api/push
   04	Asia Pacific Northeast	https://apnortheast.push.samsungosp.com:8090/spp/pns/api/push
   05	Korea	https://apkorea.push.samsungosp.com:8090/spp/pns/api/push
   06	China	https://apchina.push.samsungosp.com.cn:8090/spp/pns/api/push
   50	US East	https://useast.gateway.push.samsungosp.com:8090/spp/pns/api/push
   52	Asia Pacific Southeast	https://apsoutheast.gateway.push.samsungosp.com:8090/spp/pns/api/push
   53	EU West	https://euwest.gateway.push.samsungosp.com:8090/spp/pns/api/push
   54	Asia Pacific Northeast	https://apnortheast.gateway.push.samsungosp.com:8090/spp/pns/api/push
   55	Korea	https://apkorea.gateway.push.samsungosp.com:8090/spp/pns/api/push
   56	China	https://apchina.gateway.push.samsungosp.com.cn:8090/spp/pns/api/push

   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.

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

     {
         /* Other content */
         "message": "action=ALERT&badgeOption=INCREASE&badgeNumber=1&alertMessage=Hi",
         "appData": "{id:asdf&passwd:1234}",
         /* Other content */
     }
     

   • If you have to send data to an application without notifying the user immediately, use the action field. The action field must be used at the same level as message field, and do not include the message field itself. In this case, the notification is delivered on best-effort basis.

     {
         /* Other content */
         "action": "backgroundLaunch",
         "appData": "{id:asdf&passwd:1234}",
         /* do not include "message" field */
         /* Other content */
     }
     

     Note

     Do not confuse between “backgroundLaunch” option of action field in the 1st depth and “BACKGROUNDLAUNCH” option of action field in message field in the 2nd depth. The former is to deliver the notification with the best effort and the latter is to launch the application in the background. However, “backgroundLaunch” option also launches the application in the background.

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

   Table: Message field key-value pairs

   Key	Value	Description
   action	ALERT: Store the message and alert the user. SILENT: Store the message without alerting the user. DISCARD: Discard the message, if the application is not up and running. LAUNCH: Forcibly launch the application and deliver the notification. BACKGROUNDLAUNCH: Launch the application in the background and deliver the notification (supported since Tizen 3.0).	Action to be performed if the application is not running. If no action is defined, the default behavior is SILENT.
   alertMessage	Up to 127 bytes	Alert message shown to the user in the quick panel. If the action is not set as ALERT, this value is meaningless.
   badgeOption	INCREASE: Increase the badge number by the given value. DECREASE: Decrease the badge number by the given value. SET: Set badge number to the given value.	Option for updating the icon badge number. If the action is set as DISCARD, the badgeOption is ignored. If the badge option is not included, the icon badge number remains unchanged.
   badgeNumber	0-999	-

   For example, to show a “Hi” message in the quick panel and increase the badge count by 1 when the notification arrives at the device, the message field of the notification must be the following:

   "badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi"
   

   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.

   Note

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

4. Use the Rest APIs for sending push notifications.

   • Single request

     With the created message field, you can construct a notification using a JSON query and send it to the RQM server using the POST method. The following list contains the details:

     • URI: URI of the RQM server chosen based on the first 2 digits of the registration ID

     • Method: POST

     • Data: JSON

     • Description: Request a notification push from the push server to the push service

     • Note: The total request message body must be less than the system default value, 200 kb. If not, “3035 – error of too long chuned message data” is returned. The system default value can be changed as needed.

     • Header

       There are 2 required fields: appID and appSecret.

       The fields are given when you register the application, and they are used for application authentication. If either is missing, the push server rejects the request and returns “3045 – error of application authentication” error. Put these 2 parameters on the request header.

     • Arguments

       Table: Arguments

       Key	Description	Additional information
       encoding	Encoding defines how the regId is encoded. For most cases, the push server issues the regId as a hex string by default, but if third-party providers state that they use the base64 encoding for the regId at the application registration time, the regId is base64-encoded. If the regId is base64-encoded, use the "base64" value for this field. Otherwise, leave this field blank to allow the push server to handle the regId as a hex string.	Optional Type: string Default: NULL
       regID	Distinguish a recipient from other recipients by assigning a unique registration ID to each recipient. The registration ID is assigned when the application is installed on a device and marked to use an application service. The current registration ID passing policy is as follows (it can change in the future): The preloaded push service connects to the push server and registers the application. The push server returns the registration ID to the push service. The push service passes the ID to the application. The push server passes the registration ID to an application server. In other applications, the application passes the registration ID to the application server.	Required Type: string
       requestID	An application server needs to assign a request ID to each request. It enables you to distinguish one request from the others.	Required Type: string
       sender	Information on the user who sends the notification.	Optional Type: string 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. Maximum message length must be less than 2 kb. Make sure that if there is no message and appData, the push server rejects the message and returns an error.	Conditionally mandatory (if appData is NULL, this field is required) Type: string Default: NULL
       appData	Applications can use this field to carry their own data. The handling of this data depends on the type defined with the type key. Make sure that if there is no message and no appData, the push server rejects the message and returns an error.	Conditionally mandatory (if message is NULL, this field is required) Type: string Default: NULL
       reliableOption	The push server guarantees reliable message delivery if the reliableOption is set. The possible options are: NoReliable: Do not send any acknowledgment back to an application server and do not store the notification in the push server if the push service did not receive the notification. Transport: Send an acknowledgment back to the application server when the push service receives the notification. This is an optional field, and if it does not exist, the server applies its default value (Transport). An acknowledgment at this point does not mean a response to the notification request, but an acknowledgment that the push service has received the notification. When the push service receives the notification, the push server sends this acknowledgment to the application server in a JSON format through HTTP.	Optional Type: string Default: transport
       sessionInfo	Connection information for an application. Third-party applications can define this field by themselves.	Optional Type: string Default: NULL
       timeStamp	Server time in milliseconds when a notification request has been made.	Optional Type: long Default: NULL
       expiryDate	Time period, in minutes, for storing the request in the push server if the delivery fails: If the value set to 0, the push server stores the request for 1440 minutes (24 hours). If the value is 1 - 2800, the push server stores the request for that number of minutes. If the push server default setting is less than the defined value, the push server stores the request according to its own setting. If the value is greater than 2880, the push server stores the request for 2880 minutes (48 hours). This is an optional field, and if it does not exist, the server applies its default value (0). If reliableOption is set at NoReliable, this field is meaningless.	Optional Type: int Default: 0

     The following examples illustrate the notification:

     • Example header:

       appID: 1234567890987654
       appSecret: dYo/o/m11gmWmjs7+5f+2zLNVOc=
       

     • Example request:

       {
           "encoding": "base64" /* Optional */
           "regID": "ab123456",
           "requestID": "0000001",
           "sender": "oscal", /* Optional */
           "type": 0 /* Optional */
           "message": "badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi", /* Optional */
           "appData": "{id:asdf&passwd:1234}", /* Optional, (Opaque) */
           "sessionInfo": "002002", /* Optional */
           "timeStamp": 1234567890, /* Optional */
       }
       

     • Example response:

       If the push server receives a notification request, the server returns a JSON string that contains the regID, requestID, status code, and status message. If the request contains a malformed JSON format, requests are not processed and are returned without the regID and requestID values. If the request is of the JSON format but has invalid data, no requests are processed and are considered as an error.

       The response message only shows whether receiving the notification request was successful. The response message does not deal with whether the push service receives the notification. The order of the response message is the same as the request message order.

       • The following example shows a response message when the request is successful:

         {
             "results":
             [{
                 "regID": "ab123456",
                 "requestID": "0000001",
                 "statusCode": 1000,
                 "statusMsg": "Success"
             }]
         }
         

       • The following example shows a response message when the request fails due to malformation:

         {
             "results":
             [{
                 "regID": "",
                 "requestID": "",
                 "statusCode": 3023,
                 "statusMsg": "error of json mapping exception"
             }]
         }
         

       • The following example shows a response message when the request fails due to abnormal data:

         {
             "results":
             [{
                 "regID": "ab123456",
                 "requestID": "0000001",
                 "statusCode": 3008,
                 "statusMsg": "error of not registered regID"
             }]
         }
         

         Note

         In the above example, the 3008 error code means that the regID does not exist in the push server. It happens when your application of that particular regID was uninstalled or disabled by the user, and consequently the regID must be removed from your application server. When the application is reinstalled or enabled, it must repeat the registration process and send a new regID to your application server.

   • Multiple request

     You can construct a multiple request in a Rest API call. Currently, this feature is not supported for the registration IDs starting with 5.

     The following list contains the details:

     • URI: URI of the RQM server chosen based on the first 2 digits of the registration ID

     • Method: POST

     • Data: JSON

     • Description: Request a notification push from the push server to the push service

     • Argument: See the single request

     • Note: The total request message body must be less than the system default value, 200 kb. If not, “3035 – error of too long chuned message data” is returned. The system default value can be changed as needed.

     • Example header:

       appID: 1234567890987654
       appSecret: dYo/o/m11gmWmjs7+5f+2zLNVOc=
       

     • Example request:

       {
           "messages":
           [{
               "encoding": "base64" /* Optional */
               "regID": "ab123456",
               "requestID": "0000001",
               "sender": "oscal", /* Optional */
               "type": 0 /* Optional */
               "message": "example", /* Optional */
               "appData": "{id:asdf&passwd:1234}", /* Optional, (Opaque) */
               "reliableOption": "Transport", /* Optional */
               "sessionInfo": "192.168.0.1-8080-12345567", /* Optional */
               "timeStamp": 1234567890, /* Optional */
           }
           {
               "encoding": "base64" /* Optional */
               "regID": "ab234567",
               "requestID": "0000002",
               "sender": "oscal", /* Optional */
               "type": 0 /* Optional */
               "message": "example", /* Optional */
               "appData": "{id:asdf&passwd:1234}", /* Optional, (Opaque) */
               "reliableOption": "Transport", /* Optional */
               "sessionInfo": "192.168.0.1-8080-12345567", /* Optional */
               "timeStamp": 1234567890, /* Optional */
           ]}
       }
       

     • Example response:

       • The following example shows a response message when the request is successful:

         {
             "results":
             [{
                 "regID": "ab123456",
                 "requestID": "0000001",
                 "statusCode": 1000,
                 "statusMsg": "Success"
             }
             {
                 "regID": "ab234567",
                 "requestID": "0000002",
                 "statusCode": 1000,
                 "statusMsg": "Success"
             }]
         }
         

       • The following example shows a response message when the request fails due to malformation:

         {
             "results":
             [{
                 "regID": "",
                 "requestID": "",
                 "statusCode": 3023,
                 "statusMsg": "error of json mapping exception"
             }]
         }
         

       • The following example shows a response message when some parts of the multiple request have failed and the others have not:

         {
             "results":
             [{
                 "regID": "ab123456",
                 "requestID": "0000001",
                 "statusCode": 1000,
                 "statusMsg": "Success"
             }
             {
                 "regID": "ab234567",
                 "requestID": "0000002",
                 "statusCode": 3008,
                 "statusMsg": "error of not registered regID"
             }]
         }
         

   • Multicast

     You can construct a multicast to send a push notification to multiple applications. Currently, this feature is not supported for the registration IDs starting with 5.

     The following list contains the details:

     • URI: URI of the RQM server chosen based on the first 2 digits of the registration ID

     • Method: POST

     • Data: JSON

     • Description: Request a notification push from the push server to the push service

     • Argument: See the single request

     • Note: The total request message body must be less than the system default value, 200 kb. If not, “3035 – error of too long chuned message data” is returned. The system default value can be changed as needed.

     • Example header:

       appID: 1234567890987654
       appSecret: dYo/o/m11gmWmjs7+5f+2zLNVOc=
       

     • Example request:

       {
           "messages":
           [{
               "encoding": "base64" /* Optional */
               "regID": ["ab123456", "ab234567", "ab345678"]
               "requestID": "0000001",
               "sender": "oscal", /* Optional */
               "type": 0 /* Optional */
               "message": "example", /* Optional */
               "appData": "{id:asdf&passwd:1234}", /* Optional */
               "sessionInfo": "192.168.0.1-8080-12345567", /* Optional */
               "timeStamp": 1234567890, /* Optional */
           ]}
       }
       

     • Example response:

       • The following example shows a response message when the request is successful:

         {
             "results":
             [{
                 "regID": "ab123456",
                 "requestID": "0000001",
                 "statusCode": 1000,
                 "statusMsg": "Success"
             }
             {
                 "regID": "ab234567",
                 "requestID": "0000002",
                 "statusCode": 1000,
                 "statusMsg": "Success"
             }
             {
                 "regID": "ab345678",
                 "requestID": "0000002",
                 "statusCode": 1000,
                 "statusMsg": "Success"
             }]
         }
         

       • The following example shows a response message when the request fails due to malformation:

         {
             "results":
             [{
                 "regID": "",
                 "requestID": "",
                 "statusCode": 3023,
                 "statusMsg": "error of json mapping exception"
             }]
         }
         

       • The following example shows a response message when some parts of the multicast request have failed and the others have not:

         {
             "results":
             [{
                 "regID": "ab123456",
                 "requestID": "0000001",
                 "statusCode": 1000,
                 "statusMsg": "Success"
             }
             {
                 "regID": "ab234567",
                 "requestID": "0000001",
                 "statusCode": 3008,
                 "statusMsg": "error of not registered regID"
             }
             {
                 "regID": "ab345678",
                 "requestID": "0000001",
                 "statusCode": 3013,
                 "statusMsg": "error of impossible to enqueue"
             }]
         }
         

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 information on 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.

The following table lists the additional key and value pairs for the message field in notifications.

Table: Additional message field key and value pairs for notification

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

The following figure shows a decorated push notification.

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

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.

Table: Push notification error codes

Related Information

• Dependencies
  • Tizen 2.3 and Higher for Mobile
  • Tizen 2.3.1 and Higher for Wearable