Java

Using Java it’s quite easy to connect to the Puship management system.
Just add to the project the PushipApi.jar set the AppId relative to the application that need to be managed via API, the Username and Password, the EnableDebug(default false), and the timezone for date conversion purpose.

Credentials cr = new Credentials("MRossi", "PassWord"); //Set Username and Password 
CoreApi ca = new CoreApi("APKCbOd72fXKVUU", cr); //Set AppId and credentials on to created
//ca.Binarysupport = false; //Set only when you are using the Android library
ca.EnableDebug = true; //Shows Url, Url Parameters, Response Code, and the Response from the Server

PushipUtil.SetTimeZone("Europe/Rome");//Set the desired timezone to use during the conversion of the date coming from Puship

 

The configuration is now done and it is possible to start performing calls via the following methods:

 

 

Notifications reading

Notifications reading allow the retrieval of notifications using filters to reduce the result set, performing a more accurate search (i.e. get a notification for a specific platform and location).

Method to be used: GetPushMessages(param)

The available parameters are:

DeviceType int: Desired target platform to filter the result by (obligatory)

Limit int: Result set maximum size (default 5)

Offset long: Starting record to be used during a paginated reading (default 0)

Tags strings array: Tags used in the notification

DeviceId string: If set, all the notifications sent to this specific device would be added to the result set

Latitude double: Latitude of the location to filter by

Longitude double: Longitude of the location to filter by

IncludeParams boolean: True if you want to include the parameters of the notification (default false)

The result set is an array of objects having the following attributes:

PushMessageId string: Notification Id

Date datetime: Date and time in JSON format

Message string: Notification text

Params hashmap of strings: Parameters list, possible Keys: Param1, Param2, Param3, Param4, Param5

 

Notifications reading by Platform

To filter the notifications by Platform the parameter DeviceType need to be used.

1 = Apple

2 = GCM

3 = WP7/8

4 = BlackBerry

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("DeviceType", "1"); //Apple platform filter
JSONArray al= ca.GetPushMessages(map);

 

Notifications reading by Tag

Setting the Tags parameter, would filter the notifications by the tags that they have been associated to.

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("DeviceType", "1");
Set tagmaps = new HashSet();
tagmaps.add("Libra"); //Tag number 1
tagmaps.add("Virgo"); //Tag number 2
map.put("Tags", tagmaps);
JSONArray al= ca.GetPushMessages(map)

 

Notifications reading by Location

Fetch all the notifications sent to a device filtering on its relative location. As default, no location is specified and all the notification will be fetched regardless their location.

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("DeviceType", "1");  
map.put("Latitude", "45.44085");  //latitude of Venice city center
map.put("Longitude", "12.31552"); //longitude of Venice city center
JSONArray al= ca.GetPushMessages(map); 

 

Notifications reading with Parameters

Retrieves notifications and associated parameters. As default, the parameters are not included to minimize data transmission.

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("DeviceType", "1");
map.put("IncludeParams", "True");
JSONArray al= ca.GetPushMessages(map); 

 

Device specific notifications reading

Using the DeviceId parameter, is possible to fetch even all the notifications sent to a specific device (starting from the time of its registration) regardless the filtering. The result set in this case will be the union of the results obtained using the filter with the set of record fetched for that specific device.

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("DeviceType", "1");
map.put("DeviceId", "APKCbOd72fXKVUU_7a6ff1f023039299");
JSONArray al= ca.GetPushMessages(map); 

The request in the example, fetch all the notifications sent to Apple devices and all those sent to the device having the id APKCbOd72fXKVUU_7a6ff1f023039299.
 

Read all Notifications

Allows to retrieve all notifications sent as displayed on the Puship dashboard.

Example:

HashMap<String, Object> map= new HashMap<String, Object>();
    map.put("Limit", "10");
    map.put("Offset", "0"); 
    map.put("IncludeParams", "True");
    JSONArray al= ca.GetAllPushMessages(map); 

This request returns all push notifications adding parameters.

ATTENTION: The elements of the returned array will count the Booleans attributesSentToAPNS, SentToMPNS, SentToGCM that identify for which platform was sent the notification

 

Notifications reading by Device

In order to fetch all the notifications sent to a specific device the method to use id: GetPushMessagesByDevice (param)

The available parameters are:

DeviceId string: Id of the device on which the notifications have been sent to (obligatory)

Limit int: Result set maximum size (default 5)

Offset long: Starting record to be used during a paginated reading (default 0)

IncludeParams boolean: True if you want to include the parameters of the notification (default false)

The result set is an array of objects having the following attributes:

PushMessageId string: Notification Id

Date datetime: Date and time in JSON format

Message string: Notification text

Params hashmap of strings: Parameters list, possible Keys: Param1, Param2, Param3, Param4, Param5

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("DeviceId", "APKCbOd72fXKVUU_7a6ff1f023039299");
JSONArray al= ca.GetPushMessagesByDevice(map); 

 

App reading

This modality permit to retrieve the list of applications

The method to utilize is: GetApps (param)

The possible parameters are:

Limit int: Number maximum records returned from call (default 5)

Offset long: Record start for reading paged (default 0)

The result is an object that contain the following attributes:

AccessCode string: Application Id

Created datetime: Date and hour of creation in the json format

Updated datetime: Date and hour of latest updating in the json format

Name string: Application name

Development boolean: True if the APNS is set for the development, False if is set for the production

EnableAPNS boolean: True if the APNS is configured

EnableBPNS boolean: True if the BPNS is configured

EnableMPNS boolean: True if the MPNS is configured

EnableGCM boolean: True if the GCM is configured

Example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("Limit", "15");
map.put("Offset", "0");
JSONArray al= ca.GetApps(map);

ATTENTION: this call not necessity of setting of AppId (new CoreApi(null, cr);)

 

Notification deletion

Delete a notification based on its Id.

Method to be used: DeletePushMessage (param)

The available parameters are:

PushMessageId string: Id of the notification to be deleted (obligatory)

The result is an object having the following attributes:

Error boolean: True in case of error, false otherwise

Message string: Error message in case of error or an information message otherwise

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("PushMessageId", "APKCbOd72fXKVUU_635192605191400000"); // Id of the notification to be deleted
JSONObject al = ca.DeletePushMessage(map);

 

Elimination of devices

Permit to eliminate one list of device according their Id.

The method to utilize is: DeleteDevices (param)

The possible parameters are:

Devices array of strings: List of Id of device to eliminate (obligatory)

The result is an object that contain the following attributes:

Error boolean: Return True if there are an error

Message string: >: Message relative at the error or at the action just endend

StringParam1 string: >: If the action will complete successfully contain the number of devices that was eliminate

Example:

HashMap<String, Object> map= new HashMap<String, Object>();
Set<String> devicetodelete = new HashSet<String>();
devicetodelete.add("jS0oE8PtHcVerde_05CD0C12-35A7-4123-8E9F-AA74FF418A18"); //device id to delete
devicetodelete.add("jS0oE8PtHcVerde_0FDFED66-3CD6-4208-BAA1-90968D1AFA01"); 
devicetodelete.add("jS0oE8PtHcVerde_7a6ff0f023039299");
map.put("Devices", devicetodelete);
JSONObject al= ca.DeleteDevices(map);

 

Managing Filters

This section explain how to interact with the filters

 

Method to be used: GetAppTagFilters (param)

The available parameters are:

ReturnHystory boolean: If true, the method would return even the filters used in the past but not associated with any device at the moment (default false).

The result set is a string array.

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("ReturnHistory", "True");
JSONArray al = ca.GetAppTagFilters(map);

 

Adding a filter to the device

Questo metodo permette di aggiungere un filtro ad un device.

The method to utilize is: AddTagFilter (param)

The possible parameters are:

DeviceId string: >: Id of device for which want add the tag (obligatory)

Tag string: Tag to add at device (obligatory)

The result is an object that contain the following attributes:

Error boolean: Return True if there are an error

Message string: >: Message relative at the error or at the action just endend

Example:

HashMap<String, Object> map = new HashMap<String, Object>();
map.put("DeviceId", "jS0oE8PtHcVerde_E57F63B1-E43F-48F0-8A08-149F7168A1DE");
map.put("Tag", "Libra"); //Set the tag that you want add
JSONObject al = ca.AddTagFilter(map);

 

Removing a filter from device

This method permit to remove a filter form a device.

The method to utilize is: RemoveTagFilter (param)

The possible parameters are:

DeviceId string: >: Id of device for which want add the tag (obligatory)

Tag string: Tag that you want remove from device (obligatory)

The result is an object that contain the following attributes:

Error boolean: Return True if there are an error

Message string: >: Message relative at the error or at the action just endend

Example:

HashMap<String, Object> map = new HashMap<String, Object>();
map.put("DeviceId", "jS0oE8PtHcVerde_E57F63B1-E43F-48F0-8A08-149F7168A1DE");
map.put("Tag", "Libra"); //Set the tag that you want remove
JSONObject al = ca.RemoveTagFilter(map);

 

Removing all filters from device

This method permit to remove all of filters from a device.

The method to utilize is: CleanTagFilter (param)

The possible parameters are:

DeviceId string: >: Id of device for which want add the tag (obligatory)

The result is an object that contain the following attributes:

Error boolean: Return True if there are an error

Message string: >: Message relative at the error or at the action just endend

Example:

HashMap<String, Object> map = new HashMap<String, Object>();
map.put("DeviceId", "jS0oE8PtHcVerde_E57F63B1-E43F-48F0-8A08-149F7168A1DE"); //Removes all the tags attached to this device
JSONObject al = ca.CleanTagFilter(map);

 

Devices reading

Devices reading allow the retrieval of devices using filters to reduce the result set, performing a more accurate search (i.e. get the devices present in a specific location).

Method to be used: GetDevices (param)

The available parameters are:

DeviceType int: Desired target platform to filter the result by

Limit int: Result set maximum size (default 5)

Offset long: Starting record to be used during a paginated reading (default 0)

Tags strings array: Tags used in the notification

Expired boolean: if true, even the devices having an expired token would be returned

Point Example

P1Latitude double: Latitude of the Point 1 of the Location to filter by

P1Longitude double: Longitude of the Point 1 of the Location to filter by

P2Latitude double: Latitude of Point 2 of the Location to filter by

P2Longitude double: Longitude of Point 2 of the Location to filter by

LastPositionDate time: Date in UTC format of the location registration

LastPositionNumber int: Specifies how many positions, starting from the last one, have to be considered during the search (default infinite)

The result set is an array of objects having the following attributes:

DeviceId string: Id of the device

Expired boolean: True if the token is expired, false otherwise

DeviceType int: Device’s platform

Created datetime: Date and time of the first device registration in JSON format

Updated datetime: Date and time of the registration update in JSON format

 

Devices simple reading

The simple reading fetch all the devices that have been registered.

Usage example:

JSONArray al= ca.GetDevices();

 

Devices reading by Platform

To filter the devices by Platform the parameter DeviceType need to be used.

1 = Apple

2 = GCM

3 = WP7/8

4 = BlackBerry

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("DeviceType", "1"); //Apple platform filter
JSONArray al = ca.GetDevices(map);

 

Devices reading by Tag

Setting the Tags parameter, would filter the devices by a set of tag.

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
Set tagmaps = new HashSet();
tagmaps.add("Libra"); //Tag number 1
tagmaps.add("Virgo"); //Tag number 2
map.put("Tags", tagmaps);
JSONArray al= ca.GetDevices(map);

 

Devices reading by Area

Fetch the devices based on the registered locations.

Usage example:

HashMap<String, Object> map= new HashMap<String, Object>();
map.put("P1Latitude", "40.42163694648697"); //Set Venice area
map.put("P1Longitude", "10.299156188964844");
map.put("P2Latitude", "47.45030563100575");
map.put("P2Longitude", "15.368927001953125");
map.put("LastPositionNumber", "5"); // We want that the registration in the Venice area is one of the last 5 registrations
Calendar c = Calendar.getInstance();
c.set(2014, 5, 6, 0, 0,0); // June, 07, 2014
map.put("LastPositionDate", c.getTime()); // Shows devices registred after the chosen date
JSONArray al= ca.GetDevices(map);

 

Notification sending

Notifications can be sent using filters to better define the set of recipient (i.e. send a notification to a specific device in a specific location with a specific Tag).

Method to be used: SendPushMessage (param)

The available parameters are:

SendIOS boolean: If true, notification will be sent to iOS Platform (default false)

SendAndroid boolean: If true, notification will be sent to Android Platform (default false)

SendBB boolean: If true, notification will be sent to BlackBerry Platform (default false)

SendWP boolean: If true, notification will be sent to Wp7/8 Platform (default false)

Message string: The message to be sent

Badge int: Badge associated to the notification (default 1)

Push boolean: If true the notification will be sent, otherwise it will be saved (default true)

Sound string: Filename of the resource to play when the notification has been received (default Default)

Tags strings array: Filters the notifications by sent Tags

Point Example

P1Latitude double: Latitude of the Point 1 of the Location to filter by

P1Longitude double: Longitude of the Point 1 of the Location to filter by

P2Latitude double: Latitude of Point 2 of the Location to filter by

P2Longitude double: Longitude of Point 2 of the Location to filter by

LastPositionDate time: Date in UTC format of the location registration

LastPositionNumber int: Specifies how many positions, starting from the last one, have to be considered during the search (default infinite)

Params hashmap of strings: Map to insert generic parameters (up to 5 elements)

The result is an object having the following attributes:

Error boolean: True in case of error, false otherwise

Message string: Error message in case of error or an information message otherwise

StringParam1 string: If the action is successful done it contains the ID of the newly push created

Notification sending by Platform

A notification can be sent to a specific Platform only or to a set or Platforms. This behavior can be enebled setting to true the following parameter flags:

SendIOS

SendAndroid

SendBB

SendWP

Usage example:

HashMap<String, Object> map=  new HashMap<String, Object>();
map.put("Message", "Push sent to all WindowsPhoneDevices!");
map.put("SendIOS", "False");
map.put("SendAndroid", "False");
map.put("SendBB", "False");
map.put("SendWP", "True");
JSONArray al= ca.SendPushMessage(map);

 

Notification Sending by Tag

Allows to send notifications to a set of devices specified by a set of Tag on which the device has been registered to.

Usage example:

HashMap<String, Object> map=  new HashMap<String, Object>();
map.put("Message", "Push sent to Android devices associated to the tag Virgo or Libra!");
map.put("SendIOS", "False");
map.put("SendAndroid", "True");
map.put("SendBB", "False");
map.put("SendWP", "False");
Set tagmaps = new HashSet();
tagmaps.add("Libra"); //Tag number 1
tagmaps.add("Virgo"); //Tag number 2
map.put("Tags", tagmaps);
JSONArray al= ca.SendPushMessage(map);

 

Notification sending by Area

Allows to send notifications to a set of devices registered to a specific area.

Usage example:

HashMap<String, Object> map=  new HashMap<String, Object>();
map.put("Message", "Push sent to Android devices registered at Venice in the last 2 months");
map.put("SendIOS", "False");
map.put("SendAndroid", "True");
map.put("SendBB", "False");
map.put("SendWP", "False");
map.put("P1Latitude", "40.42163694648697"); //set Venice area
map.put("P1Longitude", "10.299156188964844");
map.put("P2Latitude", "47.45030563100575");
map.put("P2Longitude", "15.36892001953125")
Calendar c = Calendar.getInstance();
c.set(2014, 3, 6, 0, 0,0); // April, 07, 2014
map.put("LastPositionDate", c.getTime());
JSONArray al= ca.SendPushMessage(map);

 

Notification sending with Parameters

Allows to send notifications with generic parameters.

Usage example:

HashMap<String, Object> map=  new HashMap<String, Object>();
map.put("Message", "Push sent to Android devices with 5 generic parameters");
map.put("SendIOS", "False");
map.put("SendAndroid", "True");
map.put("SendBB", "False");
map.put("SendWP", "False");
HashMap<String, Object> params=  new HashMap<String, Object>(); // You can set simple text, urls, pages...
params.put("Param1", "Param number 1");
params.put("Param2", "ttps://www.facebook.com/OfficialPuship");
params.put("Param3", "index.html");
params.put("Param4", "122.45");
params.put("Param5", "Special chars:  '%1234567890\"!£$%&amp;/()=?^ιθ@#°§ω-,'"); //Max 5 params, the subsequent ones are ignored
map.put("Params", params);
JSONArray al= ca.SendPushMessage(map);

 

Notification sending by Device

Allows sending or associating a notification to one or more devices based on their own Id.

Method to be used: SendPushMessageByDevice (param)

The available parameters are:

Message string: The message to be sent

Badge int: Badge associated to the notification (default 1)

Push boolean: If true the notification will be sent, otherwise it will be saved (default true)

Sound string: Filename of the resource to play when the notification has been received (default Default)

Devices strings array: Specifies the set of devices on which the notification will be sent (at least one obligatory)

Params hashmap of strings: Map to insert generic parameters (up to 5 elements)

The result is an object having the following attributes:

Error boolean: True in case of error, false otherwise

Message string: Error message in case of error or an information message otherwise

StringParam1 string: If the action is successful done it contains the ID of the newly push created

Usage example:

HashMap<String, Object> map=  new HashMap<String, Object>();
map.put("Message", "Push sent to two specific devices!");
Set devicetosend = new HashSet();
devicetosend.add("APKCbOd72fXKVUU_b87389c9-5e86-45cd-88e0-9cc239643faf"); //Device number 1 (microsoft device)
devicetosend.add("APKCbOd72fXKVUU_7a6ff0f023039299"); //Device number 2 (android device)
map.put("Devices", devicetosend);
JSONArray al= ca.SendPushMessageByDevice(map);

 

Within the PushipApi.jar file an example covering configuration and methods usage can be found.

 

Caution: The library is not supported by versions of Java lower than 1.6.