Puship Library

This page documents all the common methods of the Puship-Plugin javascript library. 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 variable

Device Registration
Tags Management
1. Addition
2. Deletion
3. Clean
Push notification reception
Push notification reading
1. Simple reading
2. Per-Device reading
Push Notification Delete
Registering a location
Device unregistration

Device Registration

The device registration is common for all the platforms. Before calling the method Register of Puship is necessary to have configured the Phonegap-Push-Plugin and installed the Puship-plugin. A guide for all the platform is available at this link , or a specific example for cordova CLI at this link.

Register(registrationID, pushipID)

Register(registrationID, pushipID, options)

This is an example:

Puship.Register(
	data.registrationId,
	'YOUR-PUSHIP-APP-CODE',
	{
		successCallback: function (pushipresult) {
			alert("device registered with DeviceId:" + pushipresult.DeviceId());
		},
		failCallback: function (pushipresult) {
			alert("error during registration: "+ JSON.stringify(pushipresult));
		}
	}
);

The option registrationID is the data.registrationId generated by Phonegap push plugin in the method push.on(‘registration’, callback).
The option pushipID is the AppCode generated when the application was created on the puship manager.

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 Signs 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.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.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.CleanTagFilter();

Push notification reception

The receiving of notifications is completely managed by the phonegap-push-plugin, you can find a detailed guide at this link. Normally it is applied in the onDeviceReady after the call of PushNotification.init

This is an example:

push.on('notification', data => {
  console.log(data.message);
  console.log(data.title);
  console.log(data.count);
  console.log(data.sound);
  console.log(data.image);
  console.log(data.additionalData);
});

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.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);
			alert("Message 1 of "+regresult.length+": "+regresult[0].Message);
		}else{
			alert("No message found");
		}
	},
	failCallback: function (regresult){
		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 device related mode reading:

Puship.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);
			alert("Message 1 of "+regresult.length+": "+regresult[0].Message);
		}else{
			alert("No message found");
		}
	},
	failCallback: function (regresult){
		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.DeletePushMessage("APKCbOd72fXKVUU_4be87030-2eda-11e4-8c21-0800200c9a66",
	{
	successCallback: function (regresult){
		alert("Message deleted");
	},
	failCallback: function (regresult){
		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.RegisterCurrentPosition(
	{
	//callMinutes: 1,
	//enableHighAccuracy: true,
	//minimumAccuracy: 50, //Excludes positions with accuracy > 50 meters
	successCallback: function (regresult){
		alert("Position registration done");
	},
	failCallback: function (regresult){
		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 WatchPosition of geolocation plugin.

ActivateWatchPosition()

ActivateWatchPosition(options)

Below you can find an example:

Puship.ActivateWatchPosition({
	//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.

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.

StopWatchPosition()

Below you find an example:

Puship.StopWatchPosition();

Unregister device

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

UnregisterFromPuship()

UnregisterFromPuship(callbackSuccess)

UnregisterFromPuship(callbackSuccess, callbackFail)

This is an example of device unregistration:

Puship.UnregisterFromPuship( 
	function() {
		alert("success unregistered");
	},
	function(err) {
		alert("error: "+ err);
	},
);