App42 Cloud API

Java Cloud SDK

Push Notification

The service is for pushing the notifications to any device using GCM(Google Cloud Messaging). You have to upload your apikey that you received while registering for GCM and you have to store your device token with particular username. This service allows you the feature of sending message to particular channel, particular user or to all your users.For sending message to any channel, you have to create the channel and send the message to channel. The users which have subscribed to that channel will receive all the notification for that channel. For sending message to particular user, you have to pass username and message. Notification will sent to the device of registered user. The most important feature you can send your message to all your device whether it is iphone, android or blackberry.

In order to use the various functions available under a particular API, a developer will have to create an instance of ServiceAPI by passing the apiKey and the secretKey which has been received while creating an app.

		ServiceAPI api = new ServiceAPI("<API_KEY>","<SECRET_KEY>");   

After initialization, developer needs to call the buildXXXService method on ServiceAPI instance to get the instance of the particular API that you wish to build. For example, To build an instance of PushnotificationService, buildPushnotificationService() method needs to be called.

	PushnotificationService pushnotificationService = api.buildPushnotificationService();

Once the API instance has been retrieved, You are ready to use the functions available for that particular API.

The methods available under a particular API will return the domain object (like Push Notification in this case) as a response which will have the accessor / mutator to access the available properties for that object. You can get the response in the form of JSON as well. We have also provided the JSON response with every function detail which can be retrieved by calling the toString() on the returned object.

 String channel = "News Channel";
 String message = "Message which you have to send";		
			
	PushNotification pushNotification = pushnotificationService.sendPushMessageToChannel(channel, message);  /* returns the Push Notification object. */
	System.out.println("Message is " + sendPushNotificationObj.getMessage());
	ArrayList<PushNotification.Channel>channelList = sendPushNotificationObj.getChannelList();
	for(PushNotification.Channel channelObj : channelList)
	{
		System.out.println("Channel Name is " + channelObj.getName());
	}
	
	String jsonResponse = pushNotification.toString(); /* returns the response in JSON format. */                         

The functions available under Push Notification API can throw some exceptions in abnormal conditions. Example of the same has been given below.

E.g. If App developer is sending a message to channel which is not in dataBase , the function will throw the App42Exception (as shown below) with message as "Not Found" and the appErrorCode as "1702" and the details as "Channel by the name '<channelName>' does not exist.".

String channelName = "News Channel';
String message = "Message which you have to send";

try
{
	PushNotification pushNotification = pushnotificationService.sendPushMessageToChannel(channelName, message);
}
catch(App42Exception ex) 
{
	int appErrorCode = ex.getAppErrorCode();
	int httpErrorCode = ex.getHttpErrorCode();
	if(appErrorCode == 1702)
	{
		// Handle here for Not Found (Channel by the name '<channelName>' does not exist.)
	}	
	else if(appErrorCode == 1401)
	{
		// handle here for Client is not authorized
	}
	else if(appErrorCode == 1500)
	{
		// handle here for Internal Server Error
	}	
	String jsonText = ex.getMessage(); /* returns the Exception text in JSON format. (as shown below)*/	
}           
               
{
    "app42Fault": {
        "httpErrorCode": 400,
        "appErrorCode": 1702,
        "message": "Not Found",
        "details": "Channel by the name 'News Channel' does not exist"
    }
}							

Below are the HTTP Error Codes and their description, the function under the Pushnotification API can throw.

/*
1400 - BAD REQUEST - The Request parameters are invalid
1401 - UNAUTHORIZED - Client is not authorized
1500 - INTERNAL SERVER ERROR - Internal Server Error. Please try again	
*/		

Below are the Application Error Codes and their description, the function under the Pushnotification API can throw.

/*
1700 - BAD REQUEST - User by the name '<userName>' already registered with the device '<deviceToken>'.
1701 - BAD REQUEST - Channel by the name '<channelName>' already exist for user '<userName>'.
1702 - NOT FOUND - Channel by the name '<channelName>' does not exist.
1703 - NOT FOUND - User by the name '<userName>' does not have any device registered.
1704 - BAD REQUEST - User by the name '<userName>' already subscribed for the channel '<channelName>'.
1705 - NOT FOUND - User by the name '<userName>' not subscribed for the channel '<channelName>'.
1706 - NOT FOUND - No device is registered with the App.
1707 - NOT FOUND - No device is Subscribed to the channel '<channelName>'.
*/		

Various functions available under Pushnotification API has been explained below.

public PushNotification storeDeviceToken(String userName,String deviceToken, DeviceType devicetype) throws App42Exception

Stores your device token on server with particular username

Parameters:

userName - username with which you want your device to be registered
deviceToken - device id for android phones
deviceType - type of the device like Android, iOS , WP7

Returns:

PushNotification Object.

Response: PushNotification Object

Exception:

The method throws the following exception with the error code.
/*
1700 - BAD REQUEST - User by the name '<userName>' already registered with the device '<deviceToken>'
*/        
For more details click Exception
String userName = "Nick";
String deviceToken = "Device Token";

PushNotification pushNotification = pushnotificationService.storeDeviceToken(userName,deviceToken,DeviceType.ANDROID);  /* returns the PushNotification object. */ 

System.out.println("UserName is " + pushNotification.getUserName());
System.out.println("Type is " +  pushNotification.getType());
System.out.println("DeviceToken is " + pushNotification.getDeviceToken());		

String jsonResponse = pushNotification.toString(); /* returns the response in JSON format. (as shown below)*/  
{
    "app42": {
        "response": {
            "success": true,
            "push": {
                "userName": "Nick",
                "type": "Android",
                "deviceToken": "Device Token"
            }
        }
    }
}
public PushNotification createChannelForApp(String channel,String description) throws App42Exception

Create Channel for app on which user can subscribe and get the notification for that channel

Parameters:

channel - channel name which you want to create
description - description for that channel

Returns:

PushNotification Object

Response: PushNotification Object

Exception:

The method throws the following exception with the error code.
/*		   
1701 - BAD REQUEST - Channel by the name '<channelName>' already exist for user '<userName>'.
*/
For more details click Exception
String channel = "newsChannel";
String description = "channel all about the news";

PushNotification pushNotification = pushnotificationService.createChannelForApp(channel,description);  /* returns the PushNotification object. */ 
ArrayList<PushNotification.Channel> channelList = pushNotification.getChannelList();
for(PushNotification.Channel channelObj : channelList)
{
	System.out.println("channelName is " + channelObj.getName());
	System.out.println("Description is " +  channelObj.getDescription());	
}
String jsonResponse = pushNotification.toString(); /* returns the response in JSON format. (as shown below)*/  
{
    "app42": {
        "response": {
            "success": true,
            "push": {
                "channels": {
                    "channel": {
                        "channelName": "newsChannel",
                        "description": "channel all about the news"
                    }
                }
            }
        }
    }
} 	
public PushNotification subscribeToChannel(String channel,String userName) throws App42Exception

Selected User Will Be Subscribe To The Existing Channel

Parameters:

channel - the channel name which you want to subscribe
userName - username which want to subscribe

Returns:

The PushNotification Object

Response: PushNotification Object

Exception:

The method throws the following exception with the error code.
/*		   
1702 - BAD REQUEST - Channel by the name '<channelName>' does not exist.
1703 - NOT FOUND - User by the name '<userName>' does not have any device registered.
1704 - NOT FOUND - User by the name '<userName>' already subscribed for the channel '<channelName>'.
*/		       
For more details click Exception
String channelName = "newsChannel";
String userName = "Nick";

PushNotification pushNotification = pushnotificationService.subscribeToChannel(channelName,userName);  /* returns the PushNotification object. */ 
System.out.println("UserName is " + pushNotification.getUserName());
ArrayList<PushNotification.Channel> channelList = pushNotification.getChannelList();
for(PushNotification.Channel channelObj : channelList)
{
	System.out.println("channelName is " + channelObj.getName());
}	

String jsonResponse = pushNotification.toString(); /* returns the response in JSON format. (as shown below)*/  
		

{
    "app42": {
        "response": {
            "success": true,
            "push": {
                "userName": "Nick",
                "channels": {
                    "channel": {
                        "channelName": "newsChannel"
                    }
                }
            }
        }
    }
}
 
public PushNotification unsubscribeFromChannel(String channelName,String userName) throws App42Exception

Selected User Will Be Unsubscribe From The Existing Channel

Parameters:

channelName - channel name which you want to unsubscribe
userName - username which want to unsubscribe

Returns:

The PushNotification Object

Response: PushNotification Object

Exception:

The method throws the following exception with the error code.
/*		   
1702 - BAD REQUEST - Channel by the name '<channelName>' does not exist.
1703 - NOT FOUND - User by the name '<userName>' does not have any device registered.
1705 - NOT FOUND - User by the name '<userName>' not subscribed for the channel '<channelName>'.
*/        
For more details click Exception
String channelName = "newsChannel";
String userName = "Nick";

PushNotification pushNotification = pushnotificationService.unsubscribeFromChannel(channelName,userName);  /* returns the PushNotification object. */ 
System.out.println("UserName is " + pushNotification.getUserName());
ArrayList<PushNotification.Channel> channelList = pushNotification.getChannelList();
for(PushNotification.Channel channelObj : channelList)
{
	System.out.println("channelName is " + channelObj.getName());
}	

String jsonResponse = pushNotification.toString(); /* returns the response in JSON format. (as shown below)*/  
{
    "app42": {
        "response": {
            "success": true,
            "push": {
                "userName": "Nick",
                "channels": {
                    "channel": {
                        "channelName": "newsChannel"
                    }
                }
            }
        }
    }
} 
public PushNotification sendPushMessageToChannel(String channel,String message) throws App42Exception

send push message to channel containing string

Parameters:

channel - channel name which you want to send your json message
message - push message in string format

Returns:

The PushNotification Object

Response:PushNotification Object

Exception:

The method throws the following exception with the error code.
/*		   
1702 - BAD REQUEST - Channel by the name '<channelName>' does not exist.
1707 - NOT FOUND - No device is Subscribed to the channel '<channelName>'.
*/	        
For more details click Exception
String channel = "newsChannel";
String message = "Mary Kom won the bronze medal in Olympics";

PushNotification pushNotification = pushnotificationService.sendPushMessageToChannel(channel,message);  /* returns the PushNotification object. */ 
System.out.println("Message is " + pushNotification.getMessage());
ArrayList<PushNotification.Channel> channelList = pushNotification.getChannelList();
for(PushNotification.Channel channelObj : channelList)
{
	System.out.println("channelName is " + channelObj.getName());
}	

String jsonResponse = pushNotification.toString(); /* returns the response in JSON format. (as shown below)*/  
  		

{
    "app42": {
        "response": {
            "success": true,
            "push": {
                "message": "Mary Kom won the bronze medal in Olympics",
                "channels": {
                    "channel": {
                        "channelName": "newsChannel"
                    }
                }
            }
        }
    }
}	
public PushNotification sendPushMessageToAll(String message) throws App42Exception

Send push message to all your users

Parameters:

message - push message

Returns:

The PushNotification Object

Response: PushNotification Object

Exception:

The method throws the following exception with the error code.
/*		   
1706 - NOT FOUND - No device is registered with the App.
*/	        
For more details click Exception
String message = "vijay kumar shoots the silver medal";

PushNotification pushNotification = pushnotificationService.sendPushMessageToAll(message);  /* returns the PushNotification object. */ 
System.out.println("Message is " + pushNotification.getMessage());

String jsonResponse = pushNotification.toString(); /* returns the response in JSON format. (as shown below)*/  
{
    "app42": {
        "response": {
            "success": true,
            "push": {
                "message": "vijay kumar shoots the silver medal"
            }
        }
    }
}                    
public PushNotification sendPushMessageToAllByType(String message,DeviceType deviceType) throws App42Exception

Send push message to all your users

Parameters:

message - push message
deviceType - type of the device like Android, iOS , WP7

Returns:

The PushNotification Object

Response: PushNotification Object

Exception:

The method throws the following exception with the error code.
/*		   
1706 - NOT FOUND - No device is registered with the App.
*/	        
For more details click Exception
String message = "vijay kumar shoots the silver medal";

PushNotification pushNotification = pushnotificationService.sendPushMessageToAllByType(message,DeviceType.ANDROID);  /* returns the PushNotification object. */ 
System.out.println("Message is " + pushNotification.getMessage());
System.out.println("type is " + pushNotification.getType());

String jsonResponse = pushNotification.toString(); /* returns the response in JSON format. (as shown below)*/  
{
    "app42": {
        "response": {
            "success": true,
            "push": {
                "message": "vijay kumar shoots the silver medal",
                "expiry": "2012-10-15T11:03:45.425Z",
                "type": "ANDROID"
            }
        }
    }
}       
public PushNotification sendPushMessageToUser(String userName,String message) throws App42Exception

Send Push Message To paticular user in string format

Parameters:

userName - username which you want to send message
message - push message

Returns:

The PushNotification Object

Response: PushNotification Object

Exception:

The method throws the following exception with the error code.
/*		   
1703 - NOT FOUND - User by the name '<userName>' does not have any device registered.
*/	        
For more details click Exception
String userName = "Nick";
String message = "Hi Nick! you have won 10 points";

PushNotification pushNotification = pushnotificationService.sendPushMessageToUser(userName,message);  /* returns the PushNotification object. */ 
System.out.println("userName is " + pushNotification.getUserName());
System.out.println("Message is " + pushNotification.getMessage());
String jsonResponse = pushNotification.toString(); /* returns the response in JSON format. (as shown below)*/  
{
    "app42": {
        "response": {
            "success": true,
            "push": {
                "userName": "Nick",
                "message": "Hi Nick! you have won 10 points"
            }
        }
    }
}