Push

+ +

You can push events from an application server to your application on a Tizen device.

+ +

Once your application is successfully registered in the push server through the push service (daemon) on the device, your application server can send push messages to the application on that particular device.

If a push message arrives when the application is running, the message is automatically delivered to the application. If the application is not running, the push service makes a sound or vibrates and adds a ticker or a badge notification to notify the user. By touching this notification, the user can check the message. If the application server sends a message with a LAUNCH option, the push service forcibly launches the application and hands over the message to the application.

The main features of the Tizen.Messaging.Push namespace include:

Connecting to the push service +
You can establish a socket connection to the push service.
Registering with the push server +
You can obtain a registration ID to receive push notifications.
Managing security +
You need to take care of security issues when sending notifications containing sensitive information.
Sending push notifications +
You can send push notifications from the application server to an application.
Receiving push notifications +
You can receive notifications in the application at different application states.

+ +

Figure: Push messaging service

Push messaging service

+ +

Service Architecture

The following figure illustrates the service architecture of the Tizen push messaging service.

Figure: Service architecture

Service architecture

The following steps illustrate a typical scenario for using the push messaging service on a Tizen device:

The application on the device registers for the push messaging service.
When an application is installed and launched, the device establishes a push session with the Tizen Server by sending a registration request to the Tizen push server through the push service. +
The push session is managed by the Tizen server and device platform, so there is no need to create any code to manage it within the application.
If the registration request is approved, the application receives a registration ID through the push service. The registration ID is a unique key used to identify the application installed on that particular device and route the push message. +
The application delivers the registration ID to the application server. This registration ID is used to identify the application installed on that particular device.
When the application server needs to send a push message to the application on the particular device, it calls the Tizen server's open API to send the message together with the registration ID. (For more information for server developers on sending push messages, see Sending Push Notifications.) +
A text message of up to 1024 bytes can be sent in a push message. If the application needs to download a large amount of data, the application server sends a link to the data in the push message.
+
When the Tizen push server receives the message and the registration ID, it checks which device has the application with the particular registration ID and then routes the message to that device.
When the push service receives the message and the registration ID, it sends the message to the destination application, which receives the push message.

+ +

Prerequisites

+ +

To enable your application to use the push functionality:

+
To use the Tizen.Messaging.Push namespace, the application has to request permission by adding the following privilege to the tizen-manifest.xml file:
+
```
+<privileges>
+   <privilege>http://tizen.org/privilege/push</privilege>
+</privileges>
+
```
+
+
Make sure the following requirements are fulfilled:
+
1. Internet access +
  To connect to the Tizen push server and receive notifications from it, the target device or emulator must be able to contact any IP address with the port 5223. If you are in an enterprise network, ensure that the proxy setting in your local network allows outgoing traffic destined for this port number.
2. 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.
3. 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 using one of the following online request forms:
  +
  - Request the permission for a new application
  - Extend the expiration date or change the quota for an application that already has the permission to use the push messaging service
  +
  When the team approves the request, you receive a push app ID corresponding to your package ID.
  +
+
To use the methods and properties of the Tizen.Messaging.Push namespace, include it in your application: +
```
+using Tizen.Messaging.Push;
+
```
+

+ +

+ Note + The push service supports launching an application in the background. Remember that you can deliver application data to your application without an unwanted UI launch. +

+ +

Connecting to the Push Service

+ +

To manage push service connections:

Define event handlers: +

EventHandlerStateChanged() is triggered when the connection state changes.
EventHandlerNotificationReceived() is triggered when the push notification is received from the push service.

+ +

+public static void EventHandlerStateChanged(object sender, PushConnectionStateEventArgs e)
+{
+    /// State change events
+};
+
+public static void EventHandlerNotificationReceived(object sender, PushMessageEventArgs e)
+{
+    /// Notification received events
+};
+

Register the event handlers for the StateChanged and NotificationReceived events of the Tizen.Messaging.Push.PushClient class and connect to the push service with the PushServiceConnect() method: + +
```
+try
+{
+    string pushAppId = "YOUR_PUSH_APP_ID";
+
+    PushClient.StateChanged += EventHandlerStateChanged;
+    PushClient.NotificationReceived += EventHandlerNotificationReceived;
+
+    PushClient.PushServiceConnect(pushAppId);
+    PushClient.GetUnreadNotifications();
+}
+catch (Exception e)
+{
+    Console.WriteLine("Exception occurred" + e.ToString());
+}
+
```
+ +
After calling the PushServiceConnect() method, the application establishes a socket connection to the push service:
+
- The YOUR_PUSH_APP_ID parameter is the push app ID received from the Tizen push server team when the access to the server was requested. Keep this push app ID confidential, otherwise your push notifications can be hijacked by malicious applications.
- If the PushServiceConnect() method catches any exception, it means the connection to the service failed. This happens most likely when the push privilege is not added into the application manifest.
+ +
If the connection with the push service succeeds, the application must request the unread notification messages sent during the disconnected state by using the GetUnreadNotification() method.
+ +
Establish a connection to the push service when the application is launched and disconnect from the service when it terminates. The application can be resumed after being paused. To ensure that push notifications are handled fluently, the PushServiceConnect() method must be called when the application is resumed.
+
Disconnect from the push service. +
When the application terminates or no longer uses the push service, close the connection using the PushServiceDisconnect() method.
+ +
The PushServiceDisconnect() method returns all the resources allocated for the connection.
+ +
```
+PushClient.PushServiceDisconnect();
+
```
+ +
The connection is automatically closed when the application terminates. Hence, if the application uses the push service while being launched, it does not need this method.
+ +
The application can also disconnect the service in the middle of the application operation. If you add a toggle switch to the application for switching the push service on and off, call this method when the service is switched off. Do not call this method inside any event handlers, however, since it can cause the application to crash.
+
The application can be paused by pressing the Home or Back key. For a proper push operation, the PushServiceDisconnect() method must be called when the application is paused.
+
Handle state transitions. +
After the connection to the service is made, the application is notified whenever the connection state changes. This notification is conducted through the EventHandlerStateChanged() event handler. The following figure illustrates the possible states of the push service.
+ +
+ +
Once launched, the application is in the Initial state. When the application establishes a connection to the service using the PushServiceConnect() method, the state becomes either Unregistered or Registered:
+
- If the application is currently registered to the push server, the service forces it to transit from the Initial state to the Registered state. In this case, the application can request deregistration from the push server using the PushServiceDeregister() method. If this request is approved by the push server, the state transits to Unregistered.
- If the application is not currently registered to the push server, the state transits from the Initial state to the Unregistered state. In this case, the application can request registration to the push server using the PushServiceRegister() method. If this request is approved by the push server, the state transits to Registered.
- When an error occurs, the state transits to Error.
+ +
When the current state transits, the EventHandlerStateChanged() event handler is called and the new state is obtained. Determine the application actions based on the new state:
+ +
```
+public static void EventHandlerStateChanged(object sender, PushConnectionStateEventArgs e)
+{
+    switch (e.state)
+    {
+        case PushConnectionStateEventArgs.PushState.Unregistered:
+            Console.WriteLine("Arrived at STATE_UNREGISTERED");
+            OnStateUnregistered();
+            break;
+        case PushConnectionStateEventArgs.PushState.Registered:
+            Console.WriteLine("Arrived at STATE_REGISTERED");
+            OnStateRegistered();
+            break;
+        case PushConnectionStateEventArgs.PushState.StateError:
+            Console.WriteLine("Arrived at STATE_ERROR" + e.Error);
+            OnStateError();
+            break;
+        default:
+            Console.WriteLine("Unknown State");
+            break;
+    }
+}
+
```
+ +
In the above example, the OnStateRegistered(), OnStateUnregistered(), and OnStateError() methods contain the actions for the Registered, Unregistered, and StateError states, respectively. The application does not need to handle the Initial state, because it is maintained internally, and this event handler is never invoked in that state. The e.Error is the error message from the push service when the state becomes StateError.
+
The registration state is subject to change. Consequently, make sure that the application connects to the push service whenever it is launched.
+

+ +

Registering with the Push Server

+ +

To receive push notifications, the application must send a registration request to the Tizen push server. When the server receives this request, it assigns a registration ID that is unique to the application on the particular device. When sending a notification from your application server, this registration ID is used as a destination address of the application. If the application no longer needs to receive push notifications, it needs to send a deregistration request to the server.

To register with the push server:

Request registration. +
After connecting to the push service, request registration using the PushServerRegister() method of the Tizen.Messaging.Push.PushClient class.
+ +
```
+public static void OnStateUnregistered()
+{
+    Task<ServerResponse> tr = PushClient.PushServerRegister();
+    tr.GetAwaiter().OnCompleted() =>
+    {
+        ServerResponse res = tr.Result;
+    }
+}
+
```
+ +
The OnStateUnregistered() method containing the PushServiceRegister() method is called when the state transits to Unregistered. This sample application is designed to send the registration request as soon as it is connected to the push service. If the application requires users to log in to the service, this registration request must be sent after the login process is complete.
+ +
The registration request is non-blocking. If the push service successfully sends the request to the server and receives an approval, the res value is Success.
+ +
When an error occurs in the middle of the registration process, the reason is returned. For example, if the push server is not responding, the ServerResponse res returns Timeout. In this case, the application does not need to request registration again because the push service keeps the previous request and sends it when the network becomes online.
+
Handle the transit to the Registered state. +
The application transits to the Registered state in one of the following cases:
+
- The registration request sent at the Unregistered state is approved.
- The already-registered application at the Initial state is successfully connected to the push service.
+ +
In both cases, the EventHandlerStateChanged() is called with the Registered value. The application calls the OnStateRegistered() method immediately, as shown in the state transitions. When defining the actions inside the method, keep the following points in mind:
+
- If the application has already been registered, request the push service for any unread notifications that have arrived before the application is launched. +
  Request the unread notifications asynchronously. If there is such a notification, it can be received through the EventHandlerNotificationReceived() event handler after the OnStateRegistered() method returns.
- If the application is newly registered, send the registration ID issued by the push server to your application server. +
  If the ID is new or updated, you need to send it to your application server. This ID is used as a destination address to the application on a particular device. If the application has already sent the ID, you can skip this step.
+ +
```
+public static void OnStateRegistered()
+{
+    /// Request unread notifications to the push service
+    /// EventHandlerNotificationReceived() is called if there are unread notifications
+    PushClient.GetUnreadNotifications();
+
+    /// Get the registration ID
+    string id = PushClient.GetRegistrationId();
+
+    /// Send registration ID to your application server if necessary
+}
+
```
+
Request deregistration. +
When the application no longer wants to receive push notifications, use the following method to request deregistration:
+ +
```
+Task<ServerResponse> tu = PushClient.PushServerUnregister();
+tu.GetAwaiter().OnCompleted(() =>
+{
+    ServerResponse res = tu.Result;
+}
+
```
+ +
+ Note + The PushServiceUnregister() method is not used if the application is intended to receive push notifications continuously while it is installed on the device. When the application is uninstalled, the push service detects the event and deregisters the application automatically. +
On the other hand, if the application wants to receive push notifications only when a user logs in, the PushServiceUnregister() method must be called whenever the user logs out.
+
+

+ + +

Managing Security

+ +

When you send a notification with sensitive information, be aware of the chance that the notification gets hijacked by someone else. It is your responsibility to keep such sensitive information safe from malicious access. The following rules are strongly recommended:

+ +

Keep the push application ID confidential. +
If the application ID is exposed, hackers can try to hijack notifications using a fake application with the exposed ID.
Do not store the registration ID on the device. +
The registration ID can be considered as the destination address for notifications. Without the ID, hackers cannot send fake notifications to your application.
Encrypt sensitive information. +
When you send sensitive information, such as personal information and financial transactions, encrypt it and load it to the notification as a payload instead of the message field. When the notification arrives at the device, the application decrypts the payload and retrieves the sensitive information.
Do not hardcode the AppSecret in the source code. +
The AppSecret is a key to accessing the push server for sending notifications. If notifications are sent from your application server, the application does not need to know the AppSecret at all. Keep the AppSecret on the server and do not load any related information in the application. If you want device-to-device notification delivery without your application server, the application needs the AppSecret to send a notification from a device. In this case, it is your responsibility to keep the AppSecret safe.

+ + +

Sending Push Notifications

+ +

Once the application successfully sends its registration ID to the application server, you are ready to send push notifications from the application server to the application on that particular device. This use case describes how to send a simple push notification to the device. For advanced features, see the Push Server guide for server developers.

+ +

The following example shows a sample push notification:

URI: See the Push RQM (Request Manager) server URLs table.
Method: HTTP POST

Header: +

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

Body: +

+{
+    "regID": "0501a53f4affdcbb98197f188345ff30c04b-5001",
+    "requestID": "01231-22EAX-223442",
+    "message": "badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi",
+    "appData": "{id:asdf&passwd:1234}", /* Optional, if the message field is not empty */
+}
+

+ +

To send a notification:

+ +

Prepare the appID, appSecret, regID, and requestID: +
- The appID and appSecret values are given in the email message that you receive when requesting permission to use Tizen push servers.
- The regID value is the one that the application server received from your application installed on 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.
+

Use the message field to describe how to process the 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.	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"
+

+ +

If you want to deliver the notification directly to your application, the message field must be the following:

+"action=LAUNCH"
+

When the push service on the target device receives a notification with this message, it launches your application and delivers the notification. For more information, see how to receive notifications when the application is not running.

+ +

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.

Load your own data to the appData field as a string. +
This use case focuses on how an application developer can construct a notification. For advanced features, see the Push Server guide for server developers.
+

+ +

Receiving Push Notifications

+ +

When a notification arrives at the device, its delivery mechanism depends on whether the application is running.

+ +

To handle incoming push notifications:

+ +

Receive notifications when the application is running. +
When a notification arrives to the application while it is running (more precisely, while the application is connected to the service), the EventHandlerNotificationReceived() event handler is called. You can handle the received notification in the event handler.
+
The following example shows how the application can retrieve the app data (payload), message, and timestamp from the received notification. When the EventHandlerNotificationReceived() event handler is called, you can retrieve the app data, message, and time stamp from e.AppData, e.Message, and e.ReceivedAt respectively.
+ +
```
+public static void EventHandlerNotificationReceived(object sender, PushMessageEventArgs e)
+{
+    Console.WriteLine("Notification Data: " + e.AppData);
+    Console.WriteLine("Notification Message: " + e.Message);
+    Console.WriteLine("Notification Timestamp: " + e.ReceivedAt);
+    Console.WriteLine("Notification RequestId: " + e.RequestId);
+    Console.WriteLine("Notification Sender: " + e.Sender);
+    Console.WriteLine("Notification SessionInfo: " + e.SessionInfo);
+    Console.WriteLine("Notification Type: " + e.Type);
+}
+
```
+
Receive notifications when the application is not running. +
If the notification arrives when the application is not running, it can be handled in 3 ways:
+
- Forcibly launch the application and deliver the notification to it. +
  You need to set the action to LAUNCH in the message field when sending the notification from the application server. When the notification action arrives at the device, the push service forcibly launches the application and delivers the notification.
  +
  By the way, when the application is launched by the push service, you need to determine the reason for the application launch and react to it appropriately.
  + +
  The push service provides launch types when the application is launched by the service. Use the following code to figure out why the application is launched in both cases of receiving notification and changing registration state.
  +
  1. Get the requested application control: +
```
+public static Tizen.Applications.AppControl _appCtrl;
+public static Tizen.Applications.AppControl.ExtraDataCollection _extraDataSet;
+
+_appCtrl = new AppControl();
+_extraDataSet = _appCtrl.ExtraData;
+
```
    +
  2. Determine the reason for the application launch. If the reason for the launch is a notification, retrieve the latest push message. +
```
+string GettedValue = "";
+bool isGetted = _extraDataSet.TryGet("http://tizen.org/appcontrol/data/push/launch_type", out GettedValue);
+
+if (isGetted)
+{
+    if (GettedValue == "notification")
+        /// Add your code here for when push messages arrive
+    else if (GettedValue == "registration_change")
+        /// Add your code here for when registration state is changed
+}
+
```
    +
  +
- Store the notification at the push service database and request it later when the application is launched. +
  You need to set the action to ALERT or SILENT in the message field when sending the notification from the application server. When such a notification arrives at the device, the push service keeps the notification in the database and waits for the request from the application.
  +
  You can request for unread notifications from the push service. The request can be performed after connecting to the push server when the application is launched.
  +
```
+PushClient.GetUnreadNotifications();
+
```
  +
  The difference between the ALERT and SILENT actions is that the former shows an alert message in the quick panel and changes the badge count, while the latter does not. If the user clicks the alert message in the quick panel, the push service forcibly launches the application and delivers the notification through the app control.
- Discard the notification. +
  You need to set the action to DISCARD in the message field when sending the notification from the application server. When such a notification arrives at the device, the push service delivers the notification only when the application is up and running. Otherwise, the push service does not store the notification and discards it.
+

+ + + +

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:

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

+ +

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:

+ +

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.

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: +
```
+{
+    "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. +
```
+{
+    "messages":
+    [{
+        /* Other content */
+        "action": "backgroundLaunch",
+        "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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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:

+ +

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

+ +

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 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`	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"
+    }]
+}
+

+ + + +

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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

+ + + +