Php

Using PHP it’s quite easy to connect to the Puship management system. Just add to the project the PushipApi.php 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.

<?php
date_default_timezone_set('Europe/Rome'); //Set the desired timezone to use during the conversion of the date coming from Puship

require_once('PushipApi.php');

$config = array();
$config['AppId'] = 'APKCbOd72fXKVUU';
$config['Username'] = 'MRossi';
$config['Password'] = 'PassWord';

$puship = new PushipApi($config);

$puship -> EnableDebug = true; //Shows URL, URL Parameters, and the Response from the Server

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 = Android

3 = Windows

4 = BlackBerry

Usage example:

<?php
$param = array();
$param['DeviceType'] = '1'; // Apple Platform filter
$puship->GetPushMessages($param);

Notifications reading by Tag

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

Usage example:

<?php
$param = array();
$param['DeviceType'] = '1';
$tagstosend = array();
$tagstosend[0]='Virgo'; //Tag number 1
$tagstosend[1]='Libra'; //Tag number 2
$param['Tags'] = $tagstosend;
$puship->GetPushMessages($param);

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:

<?php
$param = array();
$param['DeviceType'] = '1';
$param['Latitude'] = '45.44085'; // Latitude of Venice city center
$param['Longitude'] = '12.31552'; // Longitude of Venice city center
$puship->GetPushMessages($param);

Notifications reading with Parameters

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

Usage example:

<?php
$param = array();
$param['DeviceType'] = '1';
$param['IncludeParams'] = 'True';
$puship->GetPushMessages($param);

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:

<?php
$param = array();
$param['DeviceType'] = '1';
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';  
$puship->GetPushMessages($param);

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.

Usage example:

<?php
$param = array();
$param['DeviceType'] = '1';
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';  
$puship->GetPushMessages($param);

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:

<?php
$param = array();
$param['DeviceType'] = '1';
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';  
$puship->GetPushMessagesByDevice($param);

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

Usage example:

<?php
$param = array();
$param['Limit'] = '15';
$param['Offset'] = '0';
$puship->GetApps($param);

ATTENTION: this call not necessity of setting of AppId ($config[‘AppId’] = ‘APKCbOd72fXKVUU’;)

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:

<?php
$pushparam = array();
$pushparam['PushMessageId'] = 'APKCbOd72fXKVUU_635192605191400000'; // Id of the notification to be deleted
$puship->DeletePushMessage($pushparam);

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

Usage example:

<?php
$pushparam = array();
$devicetodelete = array();
$devicetodelete[0] = 'jS0oE8PtHcVerde_05CD0C12-35A7-4123-8E9F-AA74FF418A18'; // Id of the device to be deleted
$devicetodelete[1] = 'jS0oE8PtHcVerde_0FDFED66-3CD6-4208-BAA1-90968D1AFA01'; 
$devicetodelete[2] = 'jS0oE8PtHcVerde_7a6ff0f023039299';
$pushparam['Devices'] = $devicetodelete;
$puship->DeleteDevices($pushparam);

Managing Filters

This section explain how to interact with the filters

Lecture of filters of application

Fetch filters relative to an application. 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:

Usage example:

<?php
$tagparam = array();
$tagparam['ReturnHystory']='True';
$puship->GetAppTagFilters($tagparam);

Adding a filter to the device

This method permit to add a filter at one 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

Usage example:

<?php
$param = array();
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';
$param['Tag'] = 'Libra'; // Set the tag that you want add
$puship->AddTagFilter($param);

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

Usage example:

<?php
$param = array();
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';
$param['Tag'] = 'Libra';	// Set the tag that you want remove
$puship->RemoveTagFilter($param);

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

Usage example:

<?php
$param = array();
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';
$puship->CleanTagFilter($param);

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:

<?php
$puship->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:

<?php
$param = array();
$param['DeviceType'] = '1'; // Apple Platform filter
$puship->GetDevices($param);

Devices reading by Tag

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

Usage example:

<?php
$param = array();
$tagstosend = array();
$tagstosend[0]='Virgo'; //Tag number 1
$tagstosend[1]='Libra'; //Tag number 2
$param['Tags'] = $tagstosend;
$puship->GetDevices($param);

Devices reading by Area

Fetch the devices based on the registered locations.

Usage example:

<?php
$param = array();
$param['P1Latitude'] = '40.42163694648697'; // Set Venice area
$param['P1Longitude'] = '10.299156188964844';
$param['P2Latitude'] = '47.45030563100575';
$param['P2Longitude'] = '15.368927001953125';
$param['LastPositionNumber'] = '5'; // We want that the registration in the Venice area is one of the last 5 registrations
$param['LastPositionDate'] = strtotime('-10 days UTC'); // The registration has to be done less than 10 days ago
$puship->GetDevices($param);

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:

<?php
$push = array();
$push['Message'] = 'Push sent to all Apple and Android devices!';
$push['SendIOS'] = 'True';
$push['SendAndroid'] = 'True';
$push['SendBB'] = 'False';
$push['SendWP'] = 'False';
$puship->SendPushMessage($push);

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:

<?php
$param = array();
$param['Message'] = 'Push sent to Android devices associated to the tag Virgo or Libra!';
$param['SendIOS'] = 'False';
$param['SendAndroid'] = 'True';
$param['SendBB'] = 'False';
$param['SendWP'] = 'False';
$tagstosend = array();
$tagstosend[0]='Virgo'; //Tag number 1
$tagstosend[1]='Libra'; //Tag number 2
$param['Tags'] = $tagstosend;
$puship->SendPushMessage($param);

Notification sending by Area

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

Usage example:

<?php
$param = array();
$param['Message'] = 'Push sent to Android devices registered at Venice in the last 2 months';
$param['SendIOS'] = 'False';
$param['SendAndroid'] = 'True';
$param['SendBB'] = 'False';
$param['SendWP'] = 'False';
$param['P1Latitude'] = '40.42163694648697'; // Set Venice area
$param['P1Longitude'] = '10.299156188964844';
$param['P2Latitude'] = '47.45030563100575';
$param['P2Longitude'] = '15.368927001953125';
$param['LastPositionDate'] = strtotime('-2 months UTC'); // The registration has to be done less than 2 months ago
$puship->SendPushMessage($param);

Notification sending with Parameters

Allows to send notifications with generic parameters.

Usage example:

<?php
$param = array();
$param['Message'] = 'Push sent to Android devices with 5 generic parameters';
$param['SendIOS'] = 'False';
$param['SendAndroid'] = 'True';
$param['SendBB'] = 'False';
$param['SendWP'] = 'False';
$params = array(); // You can set simple text, urls, pages...
$params['Param1'] = 'Param number 1';
$params['Param2'] = 'https://www.facebook.com/OfficialPuship';
$params['Param3'] = 'index.html';
$params['Param4'] = '122.45';
$params['Param5'] = 'Special chars:  \'%1234567890"!£$%&/()=?^éè@#°§ù-,\'';   //Max 5 params, the subsequent ones are ignored
$push['Params'] = $params;
$puship->SendPushMessage($param);

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:

<?php
$push = array();
$push['Message'] = 'Push sent to two specific devices!';
$devicestosend = array();
$devicestosend[0] = 'APKCbOd72fXKVUU_b87389c9-5e86-45cd-88e0-9cc239643faf'; //Device number 1 (microsoft device)
$devicestosend[1] = 'APKCbOd72fXKVUU_7a6ff0f023039299'; //Device number 2 (android device)
$push['Devices'] = $devicestosend;
$puship->SendPushMessageByDevice($push);

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

Download PushipApi.php + Example