Common Library

This page documents all the common methods of the Puship Notification library (PushipNotification.js). All the methods presented here are compatible with the entire set of supported platform and they will produce the same results.

All these methods belong to the Puship.Common namespace

 

Device Registration

The device registration isn’t common for all the platforms. Each of them needs specific initialization parameters to activate its push service.
Follow this guide for register with CLI, or that for recording from phonegap online build.
 

Tags Management

Tags are filters that can be associated with a specific device. In this way notifications can be sent to a group of devices, increasing the opportunities of interaction with the application and so with the user itself.
Here’s a possible scenario: Create the tag for each Zodiac Sign and send the right daily horoscope via push notification. Cool, isn’t it?
 

Adding Tags

It’s possible to add tags to a device using the following methods:

AddTagFilter(tag)

AddTagFilter(tag, options)

This is an example of tag addition:

Puship.Common.AddTagFilter(
	"Virgin", 
	{removePrevTag: true}
);

The option removePrevTag allow the previous tags to be removed.
 

Removing Tags

It’s possible to remove tags using the following method:

RemoveTagFilter(tag)

This is an example of tag removal:

Puship.Common.RemoveTagFilter("Virgin");

 

Cleaning Tags

To remove all the tags that have been associated it’s not necessary to call the removal method for each of them, the method CleanTagFilter() can be used instead:

CleanTagFilter()

This is an example of tags cleaning:

Puship.Common.CleanTagFilter();

 

Push notification reception

Reception it’s a quite trivial operation. Just implement a callback for OnPushReceived and set it in the onDeviceReady handler

OnPushReceived(pushCallBack)

This is an example of push notification reception:

Puship.Common.OnPushReceived(function(event) {
    console.log("Push received");
    console.log("Message: " + event.notification.Alert);
    console.log("Sound: " + event.notification.Sound);
    console.log("Badge: " + event.notification.Badge);
    console.log("Param1: " + event.notification.Param1);
    ...
});

 

Push notification reading

Reading notifications can be done in two modes: simple and device related.
 

Simple Mode

Simple mode allows the access to all the notifications based just on the used filer (if specified). This means that all the notifications will be available, even those ones sent before the device registration.
To perform this kind of reading, use the following method:

GetPushMessages(options)

This is an example of simple mode reading:

Puship.Common.GetPushMessages(
	{
	//limit: 10, //max limit is 50 default is 20
	//offset: 100,
	//includeParams: true,
	byCurrentPosition: false,
	tag : "Libra",
	successCallback: function (regresult){
		console.log("GetPushMessages done");

		if (regresult.length > 0)
		{
			console.log("PushMessageId: " + regresult[0].PushMessageId);
			console.log("Param1: "+ regresult[0]["Params"].Param1); // visible only if includeParams is True
			console.log("Param2: "+ regresult[0]["Params"].Param2);
			navigator.notification.alert("Message 1 of "+regresult.length+": "+regresult[0].Message);
		}else{
			navigator.notification.alert("No message found");
		}
	},
	failCallback: function (regresult){
		navigator.notification.alert("error during GetPushMessages: "+ regresult);
	}
});

Here’s the list of available options:
limit specifies the maximum amount of notification toi fetch.
offset allows to specify a starting point form notification fetching.
includeParams allows to return the parameters assigned to the current notification.
byCurrentPosition filters the notifications based on the current location of the device.
tag filters the notifications based on the tags on which there are associated to.
addDevicePush 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.
 

Device related mode

Device related mode is much strict way to get the notifications; in fact it fetches only the notifications that have been sent to that specific device.
To perform this kind of reading, use the following method:

GetPushMessagesByDevice(options)

This is an example of simple mode reading:

Puship.Common.GetPushMessagesByDevice(
	{
	//limit: 10, //max limit is 50 default is 20
	//offset: 100,
	//includeParams: true,
	successCallback: function (regresult){
		console.log("GetPushMessagesByDevice done");

		if (regresult.length > 0)
		{
			console.log("PushMessageId: " + regresult[0].PushMessageId);
			console.log("Param1: "+ regresult[0]["Params"].Param1); // visible only if includeParams is True
			console.log("Param2: "+ regresult[0]["Params"].Param2);
			navigator.notification.alert("Message 1 of "+regresult.length+": "+regresult[0].Message);
		}else{
			navigator.notification.alert("No message found");
		}
	},
	failCallback: function (regresult){
		navigator.notification.alert("error during GetPushMessagesByDevice: "+ regresult);
	}
});

Here’s the list of available options:
limit specifies the maximum amount of notification to fetch.
offset allows to specify a starting point form notification fetching.
includeParams allows to return the parameters assigned to the current notification.

In the downloadable examples you will find even code snippets for notification reading.
 

Push Notification Delete

Calling this function you can delete a notification from the server puship.

DeletePushMessage(PushMessageId)

DeletePushMessage(PushMessageId, options)

This is an example:

Puship.Common.DeletePushMessage("APKCbOd72fXKVUU_4be87030-2eda-11e4-8c21-0800200c9a66",
	{
	successCallback: function (regresult){
		navigator.notification.alert("Message deleted");
	},
	failCallback: function (regresult){
		navigator.notification.alert("Message delete error: "+ regresult);
	}
});

In the downloadable examples you will find even code snippets for notification deletion.
 

Register a location

The recording position can be made either in manual mode, both in automatic mode.

Manual Registration

It’s possible at any time, calling the following methods, to register the location of the device. As general rule of thumb, the location should be registered at startup time but it can be done even more frequently to increase the geolocalization accuracy.

RegisterCurrentPosition()

RegisterCurrentPosition(options)

This is an example location registration:

Puship.Common.RegisterCurrentPosition(
	{
     //callMinutes: 1,
     //enableHighAccuracy: true,
     //minimumAccuracy: 50, //Excludes position with accuracy > 50 meters
	successCallback: function (regresult){
		navigator.notification.alert("Position registration done");
	},
	failCallback: function (regresult){
		navigator.notification.alert("Position registration error: "+ regresult);
	}
});

The option callMinutes allows to set the time between two calls at puship server, to optimize the use of the Internet connection. Is not possible set a value less than 1 minute.
The option enableHighAccuracy allows to force the use of GPS.
The option minimumAccuracy allows to exclude positions detected with an accuracy less than accuracy set. If the accuracy detected is NULL, the position will never be discarded

 

Automatic Registration

By calling this function, you can activate the automatic registration of the device position. This function used Phonegap WatchPosition.

WatchPosition()

WatchPosition(options)

Below you can find an example:

var watchId = Puship.Common.WatchPosition({
//callMinutes: 5,
//enableHighAccuracy: true,
//minimumAccuracy: 50, //Excludes positions with accuracy > 50 meters
});

The option callMinutes allows to set the time between two calls to server puship, for optimize the internet connection. Cannot set the value less than 5 minutes.
The option enableHighAccuracy allows to force the use of GPS.
The option minimumAccuracy allows to exclude positions detected with a low accuracy of the value set. If the accuracy detected is NULL, the position will never be descarded

The return parameter watchId will have to be use to stop the automatic registration of the position through method ClearWatch.

Attention: Some versions of the operating system disables by design geolocation when the device is locked and the application is closed.

 

Disable Automatic Registration

By calling this function will be possible to deactivate the automatic registration of the position of the device.

ClearWatch(watchId)

Below you find an example:

Puship.Common.ClearWatch(watchId);

The option watchId contains the identifier of whatcher created.

 

Unregister device

Sometimes can be necessary to unregister a device. To do so these methods could be used:

UnRegister()

UnRegister(callbackSuccess)

UnRegister(callbackSuccess, callbackFail)

This is an example of device unregistration:

Puship.Common.UnRegister( 
	function() {
		navigator.notification.alert("success unregistered");
	},
	function(err) {
		navigator.notification.alert("error: "+ err);
	},
);