Push API

 

Overview

This article demonstrates the usage of Push API. Push API provides the functionality for receiving push notifications from Tizen push server. The push service maintains a permanent connection between the device and Tizen push server in order to process registration and deregistration requests, deliver push notifications to applications on a device.

Prerequisites

Add below lines in config.xml file.

<tizen:app-control>
  <tizen:src name="index.html"/>
  <tizen:operation name="http://tizen.org/appcontrol/push_test"/>
</tizen:app-control>
<tizen:privilege name="http://tizen.org/privilege/push"/>

Push API is available since tizen 2.1 for mobile profile, and since tizen 2.3.1 for wearable profile.  For more information on exporting application control, see Application Control Export.

Steps to be followed to receive Push notifications

Administrative Permission

To get the Administrative Permission for Tizen push messaging service the user has to send an email to the administrator (push.tizen@samsung.com) by filling the request form details. Tizen Push Service Team will approve the request and will send an approval email.

Register the Application

After receiving a confirmation email for the request, register the application on the device using the method registerService ( appControl, successCallback, errorCallback ). If the registration process is successful, it returns the registration identifier.

function registerSuccessCallback (id)
{
	console.log ('Registration succeeded with id: ' + id);
}

function errorCallback (response)
{
	console.log ('The following error occurred: ' +  response.name);
}

// Defines the data to be used when this process is launched by notification service.
var service = new tizen.ApplicationControl ('http://tizen.org/appcontrol/operation/push_test');

tizen.push.registerService (service, registerSuccessCallback, errorCallback);
 

Connect to Push service

Connect to the push service for receiving push notifications using connectService ( notificationCallback ) method.

function notificationCallback (noti)
{
	console.log ('Notification received with appData: ' + noti.appData);
}

tizen.push.connectService (notificationCallback);

Receive unread notifications

Get unread notifications from push service using getUnreadNotifications ( ) method.

function notificationCallback (noti)
{
	console.log ('Notification received with appData: ' + noti.appData);
}
	
tizen.push.connectService (notificationCallback);
tizen.push.getUnreadNotifications ();

Receive AppData of Push Notification from AppControl

Get appData of the push notification from the appcontrol when the application is launched by the appcontrol in config.xml. In this example, the operation for the appcontrol is “http://tizen.org/appcontrol/operation/push_test”.

var requestedAC = tizen.application.getCurrentApplication().getRequestedAppControl();
var appAC = requestedAC.appControl;
if (appAC.operation === 'http://tizen.org/appcontrol/operation/push_test')
{
    for (var i = 0; i < appAC.data.length; ++i)
    {
        if (appAC.data[i].key === 'http://tizen.org/appcontrol/data/push/appdata')
        {
            var appData = appAC.data[i].value[0];
            console.log ('appData from push notification: ' + appData);
        }
    }
}

Send Push notification request

Use Push Server API to send the notification request.

jQuery.ajax({
	type: 'POST',
	contentType: 'json',
	url: 'https://{region}.push.samsungosp.com:8088/spp/pns/api/push',
	headers: {'appID': applicationId, 'appSecret': secretId},
	data: JSON.stringify ({'regID': registrationId, 'requestID': '000001', 'message': 'badgeOption=SET&badgeNumber=10&action=ALERT&alertMessage=Hi, You got push message', 'appData': 'Hello world'}),
	dataType: 'json',
})

When a Tizen device receives the message, it is delivered to an active application directly with the appData "Hello World" and the application handles the rest of the process. If the application is not active (not running or is currently on the background), the badge number of the application is updated to 10, and a ticker message, "You've get a message", is displayed.

Refer to in “Receive unread push notifications” part of this article to get unread push notifications. It can also get the appData from appcontrol when the application is launched by a notification. To get the appData from appcontrol, refer to in “Receive AppData of Push Notification from AppControl” part of this article.

URL

To send a push notification using the POST method, the request URL is https://{region}.push.samsungosp.com:8088/spp/pns/api/push. The request URL uses only the HTTPS protocol. The {region} indicates where the Tizen Server is located and is decided by the first 2 digits of the regID.To know about Tizen server locations refer to “Sending Push Notifications” part of Push Server Guide.

Request Data Fields

Headers (appID and appSecret) are required for authentication to determine whether the application is registered and allowed to use the Tizen push service. Here appId is the ID of the application package that is using the push service and appSecret is issued by the Tizen Push Service Team ( can be found on the push service approval email).

Receiving Push notifications

If the push notification request is success, then the user receives push message from the call back of connectService ( notificationCallback ) method.

Unregister the Application

The user can unregister the an application from the Tizen push server using unregisterService(unregisterSuccessCallback, errorCallback) method.

tizen.push.unregisterService (unregisterSuccessCallback, errorCallback);

function unregisterSuccessCallback ()
{
	console.log ('Unregistration succeeded.');
}

function errorCallback (response)
{
	console.log ('The following error occurred: ' +  response.name);
}

Disconnect from Push Server

The user can disconnect from Push service and stop receiving push notifications using disconnectService() method.

tizen.push.disconnectService ();

References

Push API

File attachments: