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 PushipThe 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 = Android
3 = Windows
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("DeviceType", "1");
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 devicetodelete = new HashSet();
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
This method permit to add a filter to 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
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 = Android
3 = Windows
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(2020, 5, 6, 0, 0,0); // May, 06, 2020
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
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 Windows Devices!");
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, 5, 6, 0, 0,0); // May, 06, 2020
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\"!£$%&/()=?^ιθ@#°§ω-,'"); // 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.
Download PushipApi.jar + Example
Caution: The library is not supported by versions of Java lower than 1.6.
