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 main features of the Tizen.Messaging.Push namespace for server developers include the following:

Sending push notifications

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

Send 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, follow the steps below:

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

You can scroll this table.

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.

Determine the type of push notification.

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:


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

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:


                JSON
                
                    Copy
                    
                
            
{
    "action": "backgroundLaunch",
    "messages":
    [{
        /* Other content */
        "appData": "{id:asdf&passwd:1234}",
        /* Other content */
    ]}
}

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

You can scroll this table.

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


                plaintext
                
                    Copy
                    
                
            
"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.

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.

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

You can scroll this table.

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): a. The preloaded push service connects to the push server and registers the application. b. The push server returns the registration ID to the push service. c. The push service passes the ID to the application. d. 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`	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.	OptionalType: longDefault: `NULL`
`expiryDate`	Time period, in minutes, for storing the request in the push server if the delivery fails: - If the value is 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:


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

Example request:


                JSON
                
                    Copy
                    
                
            
{
    "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:
```
                JSON
                
                    Copy
                    
                
            
{
    "results":
    [{
        "regID": "ab123456",
        "requestID": "0000001",
        "statusCode": 1000,
        "statusMsg": "Success"
    }]
}
```
- The following example shows a response message when the request fails due to malformation:
```
                JSON
                
                    Copy
                    
                
            
{
    "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:
```
                JSON
                
                    Copy
                    
                
            
{
    "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 chunked message data” is returned. The system default value can be changed as needed.

Example header:


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

Example request:


                JSON
                
                    Copy
                    
                
            
{
    "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:


                JSON
                
                    Copy
                    
                
            
{
    "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:


                JSON
                
                    Copy
                    
                
            
{
    "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:


                JSON
                
                    Copy
                    
                
            
{
    "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 chunked message data” is returned. The system default value can be changed as needed.

Example header:


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

Example request:


                JSON
                
                    Copy
                    
                
            
{
    "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:


                JSON
                
                    Copy
                    
                
            
{
    "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:


                JSON
                
                    Copy
                    
                
            
{
    "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:


                JSON
                
                    Copy
                    
                
            
{
    "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"
    }]
}

Error codes

If sending a push notification request fails for some reason, the response message contains an error code.

The following table lists all possible error codes for push notifications, helping you to identify the reason for the failure and take appropriate action.

Table: Push notification error codes

You can scroll this table.

Status code	Basic status message
1000	Success
1001	Failed
1002	Expired
3001	Error of unknown reason
3002	Internal server error
3003	Error of no appId field
3004	Error of no deviceToken field
3005	Error of no regID field
3006	Error of no requestID field
3007	Error of at least either message or appData is needed
3008	Error of not registered regID
3009	Error of not registered appID
3010	Error of malformed notification request data
3011	Error of fatal problems with mapping of content
3012	Error of insufficient field
3013	Error of impossible enqueue
3014	Error of notification to cancel is not in queue or already sent
3015	Error of I/O produced by failed, interrupted I/O operation or unknown reason
3016	Error of not supporting requested URI
3017	Error of not supporting requested method
3018	Error of notification data contains unreadable data or `NULL`
3019	Error of containing abnormal data
3020	Error of not supported reliability option
3021	Error of bad padding exception
3022	Error of JSON parse exception
3023	Error of JSON mapping
3024	Error of illegal blocksize
3025	Error occurred while decoding regID
3026	Error of no secret key field
3027	Error of not authenticated application
3028	Error of unsupported encoding type
3029	Error of unparseable request type
3030	Error of message length excess. message length is allowed up to 2kb
3031	Error of unsupported connectionTerm
3032	Error of not supporting chunked request body
3033	Error of illegal expiry date
3034	Error of illegal delay date
3035	Error of too long chunked message data
3036	Error of empty multiple request
3037	Error of notification key generation
3038	Error of create application
3039	Error of delete application
3040	Error of read application
3041	Error of update application
3042	Error of invalid timeStamp
3043	Error of invalid type
3044	Error of not registered application
3045	Error of application authentication failed
3046	Error of not allowed to use push server

Dependencies
- Tizen 4.0 and Higher

Push Server

Send push notifications

Error codes

Related information