Mobile native Wearable native

Push: Using the Push Service

This tutorial demonstrates how you can use the Tizen push service to allow applications in a mobile device to receive notifications through the Internet even when the applications are not running.

Warm-up

Become familiar with the Push API basics by learning about:

Initializing the Push Service

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

Figure: Tizen push service architecture

Tizen push service architecture

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

  1. When an application is installed and launched, it sends a registration request to Tizen push server through the push service.
  2. If the registration request is approved, the server sends a registration ID to the application through the push service.
  3. The application sends the registration ID to the application server. This registration ID is used to identify the application installed in that particular device.
  4. When the application server needs to send a push notification to the application in that particular device, it sends the notification together with the registration ID to the push server.
  5. When the push server receives the notification and the registration ID, it checks which device has the application with the particular registration ID and then sends the notification to that device.
  6. When the push service receives the notification and the registration ID, it sends the notification to the destination application.

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

Table: Request form details
Developer information

Email address

Your email address to receive the approval response.

Last name

Your last name.

First name

Your first name.

Country

Your country of residence.
Application information

Package ID

The ID of the application package that uses the push messaging service. The package ID can be obtained from the application manifest file in the Tizen SDK.

Application name

Name of the application that uses the push service.

Application type

Native application or Web application.

Testing purpose

Yes or no. If you request the service for testing purposes only, the duration of the push service is limited to 3 weeks.

Purpose of the push notification usage

Description of how you plan to use the push service, including the situations in which you want to use it.

Application launch date

Application launch date in the YYYY/MM/DD format.
For example: 2014/08/01.

Service area/country

Service area, such as Asia, Africa, America, Europe, or the country where the application is used.

Daily push requests

Estimated number of daily notifications.

Transactions per second

Estimated peak number of transactions per second (the recommendation is below 100).

To set up the required library and privilege for the application:

  1. To use the functions and data types of the Push API (in mobile and wearable applications), include the <push-service.h> header file to your application:

    #include <push-service.h>

  2. To access the Tizen push service on the device, add the following privilege to the manifest file: 

    http://tizen.org/privilege/push

Connecting to the Push Service

To request or receive push notifications, establish a socket connection to the push service. All the information regarding this connection must be controlled by a connection handle which can be defined as a global variable:

push_service_connection_h push_conn;

To manage push service connections:

  1. Connect to the push service.

    Once the connection handle is defined, use the push_service_connect() function to connect to the push service:

    #define PUSH_APP_ID "YOUR_PUSH_ID_HERE"

static bool 
app_create(void *data)
{
   int ret;

   // Connect to the push service when the application is launched
   ret = push_service_connect(PUSH_APP_ID, _state_cb, _noti_cb, NULL, &push_conn);

   if (ret != PUSH_SERVICE_ERROR_NONE) 
   {
      // Implementation here
      dlog_print(DLOG_INFO, LOG_TAG, "push_service_connect() Failed");
   }

   return true;
}

    In the above example, the application establishes a socket connection to the push service:

    • The YOUR_PUSH_ID_HERE 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.
    • The _state_cb() and _noti_cb() parameters are callback functions called when the state changes or a notification arrives from the server through the push service.
    • The push_conn parameter is the output of the push_service_connect() function. If the connection between the application and the service is successful, the push_service_connect() function returns PUSH_SERVICE_ERROR_NONE and the push_conn connection handle is returned through the last parameter. If the push_service_connect() function returns other values, the connection to the service failed. This happens most likely when the push privilege is not added in the SDK.

    This sample application establishes a connection to the service when it is launched and disconnects from the service when it terminates. Due to this, the push_service_connect() function is located in the app_create() function, which is called when the application is launched.

  2. Disconnect from the push service.

    When the application terminates or no longer uses the push service, close the connection using the push_service_disconnect() function.

    The push_service_disconnect() function closes the existing connection associated with the push_conn handle and returns all the resources allocated for the connection.

    push_service_disconnect(push_conn);
push_conn = NULL;

    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 function. However, the application can 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 function when the service is switched off.

  3. 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 _state_cb() callback, which is defined in the push_service_connect() function. The following figure illustrates the possible states.

    State transitions

    Once launched, the application is in the INITIAL state. When the application establishes a connection to the service using the push_service_connect() function, 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 push_service_deregister() function. 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 push_service_register() function. 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 _state_cb() function is called and the new state is obtained from the first parameter. Determine the application actions based on the new state:

    static void 
_state_cb(push_service_state_e state, const char *err, void *user_data)	
{
   switch (state)	
   {
      case PUSH_SERVICE_STATE_UNREGISTERED:
         dlog_print(DLOG_INFO, LOG_TAG, "Arrived at STATE_UNREGISTERED");
         _on_state_unregistered(user_data);
         break;

      case PUSH_SERVICE_STATE_REGISTERED:
         dlog_print(DLOG_INFO, LOG_TAG, "Arrived at STATE_REGISTERED");
         _on_state_registered(user_data);
         break;

      case PUSH_SERVICE_STATE_ERROR:
         dlog_print(DLOG_INFO, LOG_TAG, "Arrived at STATE_ERROR");
         _on_state_error(err, user_data);
         break;

      default:
         dlog_print(DLOG_INFO, LOG_TAG, "Unknown State");
         break;
   }
}

    In the above example, the _on_state_registered(), _on_state_unregistered(), and _on_state_error() functions contain the actions for the REGISTERED, UNREGISTERED, and ERROR states, respectively. The application does not need to handle the INITIAL state, because it is maintained internally, and this callback function is never invoked in that state. The second parameter, err, is the error message from the push service when the state becomes ERROR. Consequently, only the _on_state_error() function takes this parameter.

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:

  1. Request registration.

    After connecting to the push service, request registration using the push_service_register() function.

    The first parameter is the connection handle that was returned from the push_service_connect() function, and the second parameter is the callback function that returns the result of the registration request.

    static void 
_on_state_unregistered(void *user_data) 
{
   int ret;

   // Send a registration request to the push service
   ret = push_service_register(push_conn, _result_cb, NULL);
}

    The _on_state_unregistered() function containing the push_service_register() function 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 login 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_register() function returns PUSH_SERVICE_ERROR_NONE, the request is successfully delivered to the push service. However, it does not necessarily mean that the request is approved by the server. If the push service successfully sends the request to the server and receives an approval, the _result_cb() callback is called with PUSH_SERVICE_RESULT_SUCCESS as the first parameter:

    static void 
_result_cb(push_service_result_e result, const char *msg, void *user_data) 
{
   if (result == PUSH_SERVICE_RESULT_SUCCESS)
      dlog_print(DLOG_INFO, LOG_TAG, "Registration request is approved.");
   else
      dlog_print(DLOG_ERROR, LOG_TAG, "Registration ERROR [%s]", msg);

   return;
}

    When an error occurs in the middle of the registration process, the reason is returned in the first parameter of the callback. For example, if the push server is not responding, the push_service_register() function returns PUSH_SERVICE_ERROR_NONE (because delivery to the service is successful), but the _result_cb() function is called later with PUSH_RESULT_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. The msg parameter is the error message from the push service if the request fails.

  2. 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 _state_cb() callback function is called with the PUSH_SERVICE_STATE_REGISTERED state. The application calls the _on_state_registered() function immediately, as shown in the state transitions. When defining the actions inside the function, keep the following points in mind:

    • If the application has already been registered, request from the service 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 _noti_cb() function after the _on_state_registered() function returns. Once the request for unread notifications is successfully delivered, PUSH_SERVICE_ERROR_NONE is returned.

    • If the application is newly registered, send the registration ID issued by the push server to your application server.

      Retrieve the registration ID from the push_conn connection handle. 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 in a particular device. If the application has already sent the ID, you can skip this step. This logic is implemented in the _send_reg_id_if_necessary() function.

    static void 
_on_state_registered(void *user_data) 
{
   int ret;
   char *reg_id = NULL;
   char *app_id = NULL;

   // Request unread notifications to the push service 
   // _noti_cb() is called if there are unread notifications
   ret = push_service_request_unread_notification(push_conn);

   // Get the registration ID
   ret = push_service_get_registration_id(push_conn, &reg_id);
   if (ret != PUSH_SERVICE_ERROR_NONE)	
   {
      dlog_print(DLOG_ERROR, LOG_TAG, "ERROR [%d]: push_service_get_registration_id()", ret);

      return;
   }

   // Send reg_id to your application server if necessary
   _send_reg_id_if_necessary(reg_id);

   if (reg_id)
      free(reg_id);
}

    Compute the hash value of the ID and compare it with the existing hash value in the _send_reg_id_if_necessary() function:

    • If they are different, the current ID is different from the previous one. In that case, send the registration ID to your application server and store the new hash value. For security, it is not safe to keep the ID as a string because it can be easily exposed.
    • If they are the same, the application server already has this registration ID. In this case, the application exits this function.
    #include <openssl/sha.h>
#define PUSH_HASH_KEY "existing_push_reg_id"

static void 
_send_reg_id_if_necessary(const char *reg_id)
{
   unsigned char md[SHA_DIGEST_LENGTH];
   char hash_string[2*SHA_DIGEST_LENGTH+1];
   char *buf_ptr = hash_string;
   char *stored_hash_value = NULL;
   int ret, i;

   // Generate a hash string from reg_id
   SHA1((unsigned char *)reg_id, sizeof(reg_id), md);

   // Convert byte array to hex string
   for (i = 0; i < SHA_DIGEST_LENGTH; i++)
   {
      buf_ptr += sprintf(buf_ptr, "%02X", md[i]);
   }
   hash_string[2*SHA_DIGEST_LENGTH] = '\0';

   // Get the saved hash string
   ret = preference_get_string(PUSH_HASH_KEY, &stored_hash_value);

   // If there is no hash string stored before or
   // if the stored hash string is different from the new one,
   // send reg_id to the server
   if (ret != PREFERENCE_ERROR_NONE || strncmp(stored_hash_value, hash_string, 2*SHA_DIGEST_LENGTH) !=0) 
   {
      // Send the reg_id to your application server
      ret = _send_reg_id(reg_id);

      // If reg_id is successfully sent, store the new hash value.
      if (!ret) 
      {
         ret = preference_set_string(PUSH_HASH_KEY, hash_string);
      }
   }
   if (stored_hash_value) 
      free(stored_hash_value);

   return;
}
  3. Request deregistration.

    When the application no longer wants to receive push notifications, use the following function to request deregistration.

    push_service_deregister(push_conn, _dereg_result_cb, NULL);

    This function is non-blocking. If it returns PUSH_SERVICE_ERROR_NONE, the request is successfully received by the push service. The result of this request is returned in the _dereg_result_cb() callback function.

    Note
    The push_service_deregister() function 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 push_service_deregister() function must be called whenever a user logs out.

Sending Push Notifications

Once the application successfully sends its registration ID to your application server, you are ready to send push notifications from your application server to the application on that particular device. This use case describes how to send a simple push notification to 1 device. For advanced features, refer to the detailed guide from the push server team.

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: RQM servers
    Prefix of the regId Region URL
    00 US East https://useast.push.samsungosp.com:8088/spp/pns/api/push
    01 US West https://uswest.push.samsungosp.com:8088/spp/pns/api/push
    02 Asia Pacific Southeast https://apsoutheast.push.samsungosp.com:8088/spp/pns/api/push
    03 EU West https://euwest.push.samsungosp.com:8088/spp/pns/api/push
    04 Asia Pacific Northeast https://apnortheast.push.samsungosp.com:8088/spp/pns/api/push
    05 Korea https://apkorea.push.samsungosp.com:8088/spp/pns/api/push>
    06 China https://apchina.push.samsungosp.com.cn:8088/spp/pns/api/push
    7C Staging (AP Northeast) https://175.41.248.50:8088/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:8088/spp/pns/api/push.

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

    LAUNCH: Forcibly launch the app 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"

    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, neither showing the "Hi" message in the quick panel nor increasing the badge count.

  3. Send notifications.

    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 to a push client
    • Note: Total request message body must be less than the system default value, 200 kb. If not, "3034 – error of too long chuned message data" is returned. 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 "3046 – error of application authentication" error. Put these 2 parameters on the request header.

    • Arguments
      Table: Arguments
      Key Description Additional information
      regID Distinguish a recipient from other recipients by assigning a unique registration ID to each recipient.

      The registration ID is assigned when a third party application is installed in a device and marked to use an application service.

      The current registration ID passing policy is as follows (it can change in the future):

      1. The preloaded push client connects to the push server and registers the third party application.
      2. The push server returns the registration ID to the push client.
      3. The push client passes the ID to the third party application.
      4. The push server passes the registration ID to a third party server.

        In other applications, the third party application passes the registration ID to the third party server.
      • Required
      • Type: string
      requestID A third party 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 of the user who sends the notification.
      • Optional
      • Type: string
      • Default: null
      message The message the sender wants to deliver. It can be a multibyte character.

      The message goes from a third party server through the push server and push client to the third party 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 Third party 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
      type This field lets the push client know how to deal with push notification messages.

      The possible field values are:

      • 0: Normal push notification to pass to an application.
      • 1: System message
      • 2: Error
      • 10-100: Embedded cases, such as 10: m.fluent
      • > 100: User-defined
      • Optional
      • Type: int
      • Default: 0
      delayDate The time how long the server holds the request before sending it to the push client.

      This is an optional field, and if it does not exist, the server applies its default values (0 minutes). If delayTime is 0, the push server delivers as soon as it receives the notification request.
      • Optional
      • Type: int
      • Unit: minute
      • Default: 0
      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 a third party server and do not store the notification in the push server if the push client did not receive the notification.
      • Transport: Send an acknowledgment back to the third party server when the push client receives the notification.
      • Application: Send an acknowledgment back to the third party server when a third party application checks 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 client has received the notification. When the push client 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 of an application. 3rd 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
      connectionTerm Determine whether the application remains registered with the push client. If the value is 0, it stays registered. If the value is 1, it does not.
      • Optional
      • Type: int
      • Default: null

    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)-->
   "delayDate" : 60, <!--Optional-->
   "reliableOption" : "Transport", <!--Optional-->
   "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 client 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"
   }]
}

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 (precisely, the application is connected to the service), the _noti_cb() function is called as defined in the push_service_connect() function. In this callback, you can handle the received notification.

    The following example shows how the application can retrieve the app data (payload), message, and timestamp from the received notification. When the _noti_cb() callback is called, obtain the notification through the first parameter. You can retrieve the app data, message, and time stamp from the handle using the push_service_get_notification_data(), push_service_get_notification_message(), and push_service_get_notification_time() functions respectively. Before exiting the function, free the data, except for the notification itself. The notification is freed automatically right after the callback.

    static void 
_noti_cb(push_service_notification_h noti, void *user_data)
{
   int ret;

   char *data=NULL; // App data loaded on the notification
   char *msg=NULL; // Noti message
   long long int time_stamp; // Time when the noti is generated
   char *sender=NULL; // Optional sender information
   char *session_info=NULL; // Optional session information
   char *request_id=NULL; // Optional request ID
   int type=0; // Optional type information

   // Retrieve app data from noti
   ret = push_service_get_notification_data(noti, &data);
   // Decrypt app data here if it is encrypted

   // Retrieve notification message from noti
   ret = push_service_get_notification_message(noti, &msg);

   // Retrieve the time when notification is created from noti
   ret = push_service_get_notification_time(noti, &time_stamp);

   // Retrieve the optional information
   ret = push_service_get_notification_sender(noti, &sender);
   ret = push_service_get_notification_session_info(noti, &session_info);
   ret = push_service_get_notification_request_id(noti, &request_id);
   ret = push_service_get_notification_type(noti, &type);

   // Use data, msg, time_stamp, sender,
   // session_info, request_id, and type as needed

   // Free all resources
   // Do not free noti in the callback function
   if (data)	
      free(data);
   if (msg)	
      free(msg);
   if (sender)	
      free(sender);
   if (session_info)	
      free(session_info);
   if (request_id)	
      free(request_id);
}
  • Receive notifications when the application is not running.

    If the notification arrives when the application is not running, there are 3 ways to handle the notification:

    • 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 as a bundle.

      When you create a project in the SDK, the app_control() function is created automatically. When the application is launched by another application or process (in this case, by the push service), all related information regarding this launch request is delivered through the app_control parameter. From this handle, retrieve the op operation using the app_control_get_operation() function. With app_control and op, retrieve the notification data using the push_service_app_control_to_noti_data() function.

      If the application is not launched by the push service, this function returns as NULL.

      static void 
app_control(app_control_h app_control, void *data)
{
   char *op = NULL;
   push_service_notification_h noti = NULL;
   int ret;

   if (app_control_get_operation(app_control, &op) < 0) 
   {
      return;
   }
	
   // Retrieve the noti from the bundle
   ret = push_service_app_control_to_notification(app_control, op, &noti);

   if (noti)
   {
      // Handle the noti

      // Free the noti
      push_service_free_notification(noti);
   }
   else 
   {
      // Case when the application is not launched by the push service
   }
   if (op)
      free(op);
}
    • 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.

      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 callback function.

    • Discard it.

      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 discards the notification unless the application is running.

  • Request unread notifications.

    If the user does not launch the application from the quick panel, the application requests the unread notifications after start-up using the asynchronous push_service_request_unread_notification() function.

    The following example shows a synchronous request using the push_service_get_unread_notification() function:

    push_service_notification_h noti;
int ret;
do 
{
   ret = push_service_get_unread_notification(push_conn, &noti);

   // Process the unread message noti

   push_server_free_notification(&noti);
} while (1);

    Call this function repeatedly until no notification is returned. If there are multiple unread notifications, the notifications are retrieved in their arrival order.

    The push_service_get_unread_notification() function blocks the code while it receives a notification from the service. Unless you need this kind of synchronous behavior, use the asynchronous function.

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 it 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 seen as a destination address of the 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. Do not load the information to the message field of the notification. 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 in 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.

Go to top