Page Example

PushReceiver Sample Overview

Mobile native

Push Receiver Sample Overview

The Push Receiver sample application demonstrates how you can receive push notification from application server through push server.

For information on creating the sample application project in the IDE, see Get Native App Samples at Tizen IDE.

The following figure illustrates the main screen of the Push Receiver sample application.

Figure: Push Receiver screen

Push Receiver Main

The application opens with the main screen, which displays just a disabled button for clearing list of push message:

  • To receive push notification, there needs either separated application server to send push request or a command for sending push notification to SPP server by using libcurl.
  • Example of the command is like below:


    curl -k --header "appID: 51642f356c585db3" --header "appSecret: 238F539EC07F2B9CAF07B9D238E15362" https://apnortheast.push.samsungosp.com:8090/spp/pns/api/push --header "Content-Type: application/json" -d "{\"regID\": \"05013fe0b87302eafcbf26e454da3fdc1e4f2bd8cad93f1ba05a97e9ced4f127afbea2510832b51b3ac1356eb78ab870d7c9-5001\", \"requestID\": \"0000001\", \"message\":\"badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi\", \"appData\": \"{id:qwer12&passwd:1234}\"}"


    To use the push messaging service, the application needs the permission to access the Tizen push server.

    • appID : "51642f356c585db3" is invalid value for example, it can be acquired trough requesting the permission to Tizen push server team, see Table: Request form details in Push guide.
    • appSecret : "238F539EC07F2B9CAF07B9D238E15362" is invalid value for example, it also can be gained with above appID.
    • URL : For information about "https://apnortheast.push.samsungosp.com:8090/spp/pns/api/push", see Table: RQM servers in Push Server guide.
    • regID : "05013fe0b87302eafcbf26e454da3fdc1e4f2bd8cad93f1ba05a97e9ced4f127afbea2510832b51b3ac1356eb78ab870d7c9-5001" is invalid value for example, and it can be issued in the progress of connecting to the push service with network connection.
    • message : For information about "badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi", see Table: Message field key-value pairs in Push Server guide.

The application uses the libpush module to receive push notification from application server and the elementary module to support the UI requirements.

Prerequisites

  • Push Receiver's SPP App ID is required to operate the application. SPP App ID does not mean "org.example.pushreceiver", but can be acquired by requesting the permisson to Tizen push server team.
  • To ensure proper application execution, the following privileges must be set in manifest file:

    • http://tizen.org/privilege/push

Implementation

Application Initialization

To initialize the application:

  1. Launch the Push Receiver, which acts connecting to the push service. push_service_connect() sets push_service_state_cb() and push_service_notify_cb() with below PUSH_APP_ID like below:
    /* below PUSH_APP_ID should be changed with your own Push App ID */
    #define PUSH_APP_ID "51642f356c585db3"
    
    push_service_connection_h push_conn = NULL;
    
    
    /*
     * function to connect Push Receiver with Push Service
     */
    static bool
    connect_push_service(void)
    {
       dlog_print(DLOG_DEBUG, LOG_TAG, "Push Receiver is connected with push service");
    
       /* Connect to push service when the app is launched */
       int ret = push_service_connect(PUSH_APP_ID, registration_state_cb, notification_msg_cb, NULL, &push_conn);
       if (ret != PUSH_SERVICE_ERROR_NONE) {
          dlog_print(DLOG_DEBUG, LOG_TAG, "ERROR : push_service_connect() is failed [%d : %s]", ret, get_error_message(ret));
          push_conn = NULL;
          return false;
       }
    
       return true;
    }
    
    
    /*
     * app create callback
     */
    static bool
    app_create(void *data)
    {
       /* Hook to take necessary actions before main event loop starts
          Initialize UI resources and application's data
          If this function returns true, the main loop of application starts
          If this function returns false, the application is terminated */
    
       dlog_print(DLOG_DEBUG, LOG_TAG, "Push Receiver Create started");
    
       if (!push_conn) {
          bool ret = connect_push_service();
          /* If connect_push_service() is failed, Push Receiver will be terminated */
          if (!ret) {
             dlog_print(DLOG_DEBUG, LOG_TAG, "connect to push service is failed, application will be terminated");
             return false;
          }
       }
    
       /* app_data for drawing main UI interface */
       appdata_s *ad = data;
       /* Create base UI of application */
       create_base_gui(ad);
    
       return true;
    }
    
  2. Then, the registration_state_cb() is invoked for refreshing the registration state as Unregistered. In the case of Unregistered, An application needs to be registered to the push server through push_service_register().

    After using the API, registration_result_cb() can receive the result of it. Also, registration_state_cb() will be invoked again for refreshing the state of registration.

    /*
     * registration result callback
     */
    static void
    registration_result_cb(push_service_result_e result, const char *msg, void *user_data)
    {
       /* Also, registration_state_cb will be invoked */
       if (result == PUSH_SERVICE_RESULT_SUCCESS) {
          dlog_print(DLOG_DEBUG, LOG_TAG, "Registration request is approved.");
       } else
          dlog_print(DLOG_ERROR, LOG_TAG, "Registration ERROR [%s]", msg);
    
       return;
    }
    
    
    /*
     * registration state callback
     */
    static void
    registration_state_cb(push_service_state_e state, const char *err, void *user_data)
    {
       switch (state) {
       case PUSH_SERVICE_STATE_UNREGISTERED:
          dlog_print(DLOG_DEBUG, LOG_TAG, "Registration state is set as UNREGISTERED");
          handle_push_state("UNREGISTERED", user_data);
          on_state_unregistered(user_data);
          /* Register to push server */
          push_service_register(push_conn, registration_result_cb, user_data);
          break;
    
       case PUSH_SERVICE_STATE_REGISTERED:
          dlog_print(DLOG_DEBUG, LOG_TAG, "Registration state is set as REGISTERED");
          handle_push_state("REGISTERED", user_data);
          /*
           * Important : you can get registration ID and send it to your app server if you need
           * You must check if registration ID was changed
           */
          on_state_registered(push_conn, user_data);
          break;
    
       case PUSH_SERVICE_STATE_ERROR:
          dlog_print(DLOG_DEBUG, LOG_TAG, "Registration state has an ERROR");
          handle_push_state("ERROR", user_data);
          on_state_error(err, user_data);
          break;
    
       default:
          dlog_print(DLOG_DEBUG, LOG_TAG, "Registration state is UNKNOWN [%d]", (int)state);
          break;
       }
    
       if (err)
          dlog_print(DLOG_DEBUG, LOG_TAG, "State error message [%s]", err);
    }
    
  3. After registration the application to push server, request unread notification messages which arrived before registered state and store gotten registration ID:
    /*
     * registration state callback for registered
     */
    void
    on_state_registered(push_service_connection_h push_conn, void *user_data)
    {
       RETURN_IF_FAIL(push_conn);
    
       /* Request unread notifications to the push service. */
       /* notification_message_cb() will be called if there is any unread notification. */
       int ret = push_service_request_unread_notification(push_conn);
       if (ret != PUSH_SERVICE_ERROR_NONE) {
          dlog_print(DLOG_ERROR, LOG_TAG, "ERROR : push_service_request_unread_notification() is failed [%d : %s]", ret, get_error_message(ret));
          return;
       }
    
       /* Get the registration id */
       char *reg_id = NULL;
       ret = push_service_get_registration_id(push_conn, &reg_id);
       if (ret != PUSH_SERVICE_ERROR_NONE || !reg_id) {
          dlog_print(DLOG_ERROR, LOG_TAG, "ERROR : push_service_get_registration_id() is failed [%d : %s]", ret, get_error_message(ret));
          return;
       }
    
       /* Send reg_id to your application server if it is necessary */
       send_reg_id_if_necessary(reg_id);
    
       free(reg_id);
    }
    

Push Notification

To receive a push notification:

action=ALERT

Figure: Push Message with ALERT

Push Message Alert Push Message Alert Push Message Alert

  1. When the application server sent a push notification, the message is delivered to the push service through push server. Without launching the application, in the case of action=ALERT, notification panel is generated and the number of badge is incresed by push service.
  2. If once the notification panel is clicked like above second picture, the application is launched and starts getting unread push messages. That process includes parsing arrived push messages and displaying those.
    • With starting the application, first of all, the notification_message_cb() is invoked.
      /*
       * notification message callback
       */
      static void
      notification_message_cb(push_service_notification_h noti, void *user_data)
      {
         dlog_print(DLOG_DEBUG, LOG_TAG, "Push Notification arrived");
         parse_notification_data(noti, user_data);
      }
      
    • Then, get notification data, message, and time which are for parsing push information.
      /*
       * parse notification data
       */
      void
      parse_notification_data(push_service_notification_h noti, void *user_data)
      {
         char *data = NULL;                        /* App data loaded on the notification */
         char *msg = NULL;                         /* Notification message */
         long long int time_stamp = 0LL;           /* Time when the noti is generated */
      
         if (!noti) {
            dlog_print(DLOG_ERROR, LOG_TAG, "Notification is Null");
            return;
         }
      
         /* Retrieve app data from notification handle */
         int ret = push_service_get_notification_data(noti, &data);
         if (ret != PUSH_SERVICE_ERROR_NONE)
            dlog_print(DLOG_ERROR, LOG_TAG, "ERROR : Fail to get notification data [%d : %s]", ret, get_error_message(ret));
      
         /* Retrieve notification message from notification handle */
         ret = push_service_get_notification_message(noti, &msg);
         if (ret != PUSH_SERVICE_ERROR_NONE)
            dlog_print(DLOG_ERROR, LOG_TAG, "ERROR : Fail to get notification message [%d : %s]", ret, get_error_message(ret));
      
         /* Retrieve the time from notification handle */
         ret = push_service_get_notification_time(noti, &time_stamp);
         if (ret != PUSH_SERVICE_ERROR_NONE)
            dlog_print(DLOG_ERROR, LOG_TAG, "ERROR : Fail to get notification time [%d : %s]", ret, get_error_message(ret));
      
         /* Your implementation here to use type, data, msg, and time_stamp */
         handle_push_message(data, msg, time_stamp, user_data);
      
         /* Do not free noti in the callback function */
      
         /* Free data and message */
         if (data)
            free(data);
         if (msg)
            free(msg);
      }
      
    • Motify the gotten data for the customized purpose.
      /*
       * function for handling push message
       */
      void
      handle_push_message(const char *data, const char *msg, long long int time_stamp, void *user_data)
      {
         /* Custom protocol parsing logic for sample */
         dlog_print(DLOG_DEBUG, LOG_TAG, "[Noti Data] push data : [%s]", data);
         dlog_print(DLOG_DEBUG, LOG_TAG, "[Noti Data] message : [%s]", msg);
         dlog_print(DLOG_DEBUG, LOG_TAG, "[Noti Data] time stamp : [%lld]", time_stamp);
      
         /* Get action value and alertMessage value */
         char *action = get_value_from_message(strdup(msg), "action");
         char *alert_message = get_value_from_message(strdup(msg), "alertMessage");
         dlog_print(DLOG_DEBUG, LOG_TAG, "------------- action: [%s] ---------------", action);
         dlog_print(DLOG_DEBUG, LOG_TAG, "------------ alert_message: [%s] ------------", alert_message);
      
         RETURN_IF_FAIL(action);
         RETURN_IF_FAIL(alert_message);
      
         /* Create arrival time & message */
         char buf_msg[512];
         sprintf(buf_msg, "Type : ");
         strcat(buf_msg, action);
         strcat(buf_msg, " / ");
         strcat(buf_msg, "Message : ");
         strcat(buf_msg, alert_message);
      
         time_t timer = time(NULL);
         struct tm *t;
         t = localtime(&timer);
         char buf_time[512];
         sprintf(buf_time, "%d%02d%02d %02d:%02d:%02d", t->tm_year + 1900, t->tm_mon + 1, t->tm_mday, t->tm_hour, t->tm_min, t->tm_sec);
      
         dlog_print(DLOG_DEBUG, LOG_TAG, "display_msg: [%s]", buf_msg);
         dlog_print(DLOG_DEBUG, LOG_TAG, "display_time: [%s]", buf_time);
      
         bundle *msg_bundle = bundle_create();
         if (msg_bundle) {
            /* Payload push message to bundle object */
            bundle_add_str(msg_bundle, BUNDLE_KEY_MSG, strdup(buf_msg));
            dlog_print(DLOG_DEBUG, LOG_TAG, "message [%s], key [%s]", buf_msg, BUNDLE_KEY_MSG);
            bundle_add_str(msg_bundle, BUNDLE_KEY_TIME, strdup(buf_time));
            dlog_print(DLOG_DEBUG, LOG_TAG, "time [%s], key [%s]", buf_time, BUNDLE_KEY_TIME);
            deliver_message(msg_bundle);
         }
      
         bundle_free(msg_bundle);
         /* Custom protocol logic End */
      }
      
    • Store and display information of the push message.
      /*
       * deliver_message() for receiving push messages from push_data_handler.c
       */
      void
      deliver_message(bundle *msg_bundle)
      {
         dlog_print(DLOG_DEBUG, LOG_TAG, "deliver_message() operates saving and showing push messages");
         if (msg_bundle) {
            char *text = NULL;
      
            /* Store push message */
            int ret = bundle_get_str(msg_bundle, BUNDLE_KEY_MSG, &text);
            if (!ret && text) {
               dlog_print(DLOG_DEBUG, LOG_TAG, "Push on message port : [%s]", text);
               /* Save message if necessary */
               save_message(text);
            }
      
            /* Store verification time and display push message and time */
            ret = bundle_get_str(msg_bundle, BUNDLE_KEY_TIME, &text);
            if (!ret && text) {
               dlog_print(DLOG_DEBUG, LOG_TAG, "Push on time port : [%s]", text);
               /* Save time if necessary */
               save_time(text);
               /* UI display function not for changed registration state but arrived push notification*/
               display_message(text);
            }
         }
      }
      

action=LAUNCH

Figure: Push Message with LAUNCH

Push Message Launch Push Message Launch

  1. When the application server sent a push notification, the message is delivered to the push service through push server. Without launching the application, in the case of action=LAUNCH, it is launched automatically by push service.
  2. If once the application is launched, it starts getting unread push messages. This process includes Parsing arrived push messages and displaying that like above action=ALERT.

Request Unread Notification

To get unread push messages:

    Push Service stores notification in its DB during pausing app. Also, unread notification can be requested in app resume callback by using push_service_request_unread_notification(). Then, Push Receiver can get unread push messages through notification message callback.
    /*
     * app pause callback
     */
    static void
    app_pause(void *data)
    {
       /* Take necessary actions when application becomes invisible */
       dlog_print(DLOG_DEBUG, LOG_TAG, "Push Receiver Pause");
    
       /*
        * Disconnect Push Receiver from Push Service
        * for re-connection when the application is resume
        */
       if (push_conn)
          push_service_disconnect(push_conn);
    
       push_conn = NULL;
    }
    
    
    /*
     * app resume callback
     */
    static void
    app_resume(void *data)
    {
       /* Take necessary actions when application becomes visible */
       dlog_print(DLOG_DEBUG, LOG_TAG, "Push Receiver Resume");
    
       /* Retry connect with Push Service for proper operation */
       if (push_conn)
          push_service_disconnect(push_conn);
    
       push_conn = NULL;
    
       bool ret = connect_push_service();
       if (ret) {
          /*
           * If connection with Push Service is succeeded,
           * Push Receiver should request unread notification messages
           * which are sent during disconnected state
           */
          int result = push_service_request_unread_notification(push_conn);
          if (result != PUSH_SERVICE_ERROR_NONE) {
             dlog_print(DLOG_ERROR, LOG_TAG, "ERROR : push_service_request_unread_notification() is failed [%d : %s]", result, get_error_message(result));
             return;
          }
       }
    }
    
Go to top