libreria Puship

Questa pagina documenta tutti i metodi comuni presenti nella libreria javascript del Puship-Plugin, questo significa che i metodi qui presenti sono compatibili con tutte le piattaforme e andranno a produrre gli stessi risultati.

Tutti i metodi comuni si trovano all’interno della variabile Puship

Registrazione del device

La registrazione del device è ora comune fra tutte le piattaforme. Prima di chiamare il metodo Register di Puship va però configurato il Phonegap-Push-Plugin e installato il Puship-plugin. Trovate una guida per tutte le piattaforme a questo link, oppure un esempio specifico per cordova CLI a questo link.

Register(registrationID, pushipID)

Register(registrationID, pushipID, options)

Di seguito trovate un esempio:

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));
		}
	}
);

L’opzione registrationID è il data.registrationId generato dal Phonegap push plugin nel metodo push.on(‘registration’, callback).
L’opzione pushipID è l’AppCode generato quando crei l’applicazione nel puship manager.

Gestione Tags

I tag non sono altro che dei filtri associabili a un determinato device. In questo modo si riescono ad inviare le notifiche push selettivamente creando maggiori opportunità di interazione con l’applicazione e quindi con l’utente.
Ad esempio si possono creare dei tag per ogni segno zodiacale, per poi inviare l’oroscopo selettivamente, via notifica push, ad ogni determinato tag… forte no?

Aggiungere Tags

E’ possibile aggiungere dei tag al dispositivo attraverso i seguenti metodi:

AddTagFilter(tag)

AddTagFilter(tag, options)

Di seguito trovate un esempio:

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

L’opzione removePrevTag consente di rimuovere i tag precedentemente inseriti.

Rimuovere Tags

E’ possibile rimuovere dei tag al dispositivo attraverso il seguente metodo:

RemoveTagFilter(tag)

Di seguito trovate un esempio:

Puship.RemoveTagFilter("Virgin");

Pulisci Tags

Per poter rimuovere tutti i tag precedentemente associati è sufficiente chiamare il metodo CleanTagFilter:

CleanTagFilter()

Di seguito trovate un esempio:

Puship.CleanTagFilter();

Ricezione delle notifiche push

La ricezione delle notifiche è gestita completamente dal phonegap-push-plugin, è possibile trovare una guida dettagliata a questo link. Di norma viene inserita nel onDeviceReady dopo la chiamata al PushNotification.init

Di seguito trovate un esempio:

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);
});

Lettura notifiche Push

La lettura delle notifiche push può essere effettuata sia in modalità semplice, sia in riferimento al device che ne sta facendo richiesta.

Lettura semplice

La lettura semplice consente di accedere alle tutte le notifiche basandosi solamente sul filtro utilizzato (se utilizzato), questo permette di accedere a notifiche push passate, inviate cioè prima che il device si registrasse per la ricezione.
Il seguente metodo ritorna le push in modalità semplice:

GetPushMessages(options)

Di seguito trovate un esempio:

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); // visibile solo se includeParams è 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);
	}
});

L’opzione limit consente di limitare il numero di push ricevute dalla funzione.
L’opzione offset consente di impostare un puntatore di partenza per la query delle notifiche.
L’opzione includeParams consente di ritornare anche i parametri assegnati alla notifica corrente.
L’opzione byCurrentPosition consente di filtrare per le notifiche push in base alla posizione corrente del device.
L’opzione tag consente di filtare le notifiche in base ai tag alle quali sono state associate.
L’opzione addDevicePush consente di aggiungere ai risultati dei precedenti filtri tutte le notifiche che il dispositivo ha ricevuto dal momento in cui è stato registrato.

Lettura per device

La ricezione per device è invece più restrittiva, essa ritorna solo le notifiche che sono state inviate specificatamente a questo determinato device.
Il seguente metodo ritorna le push in riferimento al device:

GetPushMessagesByDevice(options)

Di seguito trovate un esempio:

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); // visibile solo se includeParams è 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);
	}
});

L’opzione limit consente di limitare il numero di push ricevute dalla funzione.
L’opzione offset consente di impostare un puntatore di partenza per la query delle notifiche.
L’opzione includeParams consente di ritornare anche i parametri assegnati alla notifica corrente.

Negli esempi scaricabili per la registrazione delle varie piattaforme è possibile trovare anche il codice di esempio per la lettura delle notifiche.

Eliminazione di una notifica

Chiamando questa funzione sarà possibile eliminare una notifica dal server puship.

DeletePushMessage(PushMessageId)

DeletePushMessage(PushMessageId, options)

Di seguito trovate un esempio:

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

Negli esempi scaricabili per la registrazione delle varie piattaforme è possibile trovare anche il codice di esempio per l’eliminazione di una notifica.

Registrare una posizione

La registrazione delle posizioni può essere effettuata sia in modalità manuale, sia in modalità automatica.

Registrazione Manuale

Chiamando questa funzione sarà possibile registrare in qualsiasi momento la posizione del dispositivo. E’ buona norma aggiornare la posizione al momento dell’avvio dell’applicazione ma nulla vieta che essa sia effettuata più di frequente in modo da fornire una geolocalizzazione più accurata.

RegisterCurrentPosition()

RegisterCurrentPosition(options)

Di seguito trovate un esempio:

Puship.RegisterCurrentPosition(
	{
	//callMinutes: 1,
	//enableHighAccuracy: true,
	//minimumAccuracy: 50, //Esclude le posizioni con accuratezza rilevata > 50 metri
	successCallback: function (regresult){
		alert("Position registration done");
	},
	failCallback: function (regresult){
		alert("Position registration error: "+ regresult);
	}
});

L’opzione callMinutes consente di impostare il tempo fra una chiamata e la successive al server puship, per ottimizzare l’utilizzo della banda. Non è possibile impostare un valore minore di 1 minuti.
L’opzione enableHighAccuracy consente di forzare l’utilizzo del GPS.
L’opzione minimumAccuracy consente di escludere le posizioni rilevate con una accuratezza rilevata minore di quella impostata. Se l’accuratezza rilevata è NULL la posizione non viene mai scartata

Registrazione Automatica

Chiamando questa funzione sarà possibile attivare la registrazione automatica della posizione del device. Questa funzionalità sfrutta la funzione WatchPosition di Phonegap.

ActivateWatchPosition()

ActivateWatchPosition(options)

Di seguito trovate un esempio:

Puship.ActivateWatchPosition({
	//callMinutes: 5,
	//enableHighAccuracy: true,
	//minimumAccuracy: 50, //Esclude le posizioni con accuratezza rilevata > 50 metri
});

L’opzione callMinutes consente di impostare il tempo fra una chiamata e la successive al server puship, per ottimizzare l’utilizzo della banda. Non è possibile impostare un valore minore di 5 minuti.
L’opzione enableHighAccuracy consente di forzare l’utilizzo del GPS.
L’opzione minimumAccuracy consente di escludere le posizioni rilevate con una accuratezza rilevata minore di quella impostata. Se l’accuratezza rilevata è NULL la posizione non viene mai scartata

Attenzione: Alcune versioni dei sistemi operativi disabilitano by design la geolocalizzazione quando il device viene bloccato o si esce dall’applicazione.

Disabilitazione Registrazione Automatica

Chiamando questa funzione sarà possibile disattivare la registrazione automatica della posizione del device.

StopWatchPosition()

Di seguito trovate un esempio:

Puship.StopWatchPosition();

Deregistrare un device

A volte può essere necessario deregistrare il dispositivo, per farlo è sufficiente uno dei seguenti metodi:

UnregisterFromPuship()

UnregisterFromPuship(callbackSuccess)

UnregisterFromPuship(callbackSuccess, callbackFail)

Di seguito trovate un esempio:

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