Orientación sobre la libreria common

Esta página documenta todos los métodos comunes presente en la librería (PushipNotification.js), esto significa que los métodos aquí presente son compatibles con todas las Plataformas e irán a producir lo mismos resultados.

Todos los métodos comunes se encuentran al interno del namespace Puship.Common

 

REGISTRACIÓN DEL DEVICE

La registración del Device no es una cosa común a todas las Plataformas, por eso cada una necesita de diferentes parámetros para poder empezar el relativo servicio de Push.
Sigue esta guía para la registración desde la CLI, o que para la registración de phonegap online build.
 

GESTIÓN DE LOS TAGS

Los Tag son simplemente los filtros asociables a un determinado Device. En este modo permite de enviar notificaciones Push selectivamente creando más oportunidades de interactuar con la aplicación y también con el usuario.
Por ejemplo se puede crear Tag para cada signo zodiacal, para enviar después el horóscopo selectivamente, tramite una notificación Push, a cada Tag que queremos.

 

ADJUNTAR TAGS

Es posible adjuntar los Tag al dispositivo utilizando los siguientes métodos:

AddTagFilter(tag)

AddTagFilter(tag, options)

Ejemplo:

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

La opción removePrevTag permite de remover los Tag que inserimos precedentemente.
 

REMOVER LOS TAGS

Es posible remover los Tag del dispositivo utilizando el siguiente método:

RemoveTagFilter(tag)

Ejemplo:

Puship.Common.RemoveTagFilter("Virgin");

 

LIMPIAR LOS TAGS

Para poder remover todos los Tag precedentemente asociados es suficiente llamar el método CleanTagFilter():

CleanTagFilter()

Ejemplo:

Puship.Common.CleanTagFilter();

 

RECEPCIÓN DE NOTIFICACIONES PUSH

La recepción de notificaciones Push por cuanto se pueda pensar es una operación muy simple, será suficiente, registrarse OnPushReceived siguiendo el siguiente método:

OnPushReceived(pushCallBack)

Ejemplo:

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

 

Lectura de notificaciones Push

La lectura de notificaciones Push puede ser efectuada en modalidad simple, y también en relación al Device que la solicita.
 

SIMPLE LECTURA

La simple lectura permite de acceder a todas las notificaciones basándose solamente en el filtro utilizado( solo si utilizado), esto permite de acceder a notificaciones Push ya enviadas antes que el Device fuera registrado para la recepción.
El siguiente método devuelve las Push en modalidad simple:

GetPushMessages(options)

Ejemplo:

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 permite de limitar el número de Push recibidas por la función.
offset permite de ajustar un punto de salida para la Query de las notificaciones
includeParams permite de devolver también los parámetros seleccionados para la notificación actual
byCurrentPosition permite de filtrar par las notificaciones Push conforme a la ubicación actual del Device
tag permite de filtrar las notificaciones conforme a los Tag a la cual fueron asociadas
addDevicePush permite de integrar a los resultados de los precedentes filtros todas las notificaciones que el dispositivo ha recibido del momento en el que fue registrado
 

LECTURA POR DEVICE

La recepción por Device es más restrictiva, solo devuelve las notificaciones che fueron enviadas específicamente a este determinado Device
El siguiente método devuelve las Push con al Device:

GetPushMessagesByDevice(options)

Ejemplo:

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

Aquí está la lista de las opciones disponibles :
limit permite de limitar el número de Push recibida por la función
offset permite de ajustar un punto de salida para la Query de las notificaciones
includeParams permite de devolver también los parámetros que fueron seleccionados para la notificación actual

En los ejemplos descargables para la registracion de las diferentes plataformas es posible encontrar también el código de ejemplo para la lectura de las notificaciones.
 

Eliminación de una notificación

Llamndo esta función será posible eliminar una notificación del server Puship.

DeletePushMessage(PushMessageId)

DeletePushMessage(PushMessageId, options)

Ejemplo:

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

En los ejemplos descargables para la registracion de las diferentes plataformas es posible encontrar también el código de ejemplo para la eliminación de una notificación.
 

REGISTRACION DE UNA POSICIÓN

La registración de las posiciones puede ser efectuada en modalidad manual y en modalidad automática.

 

Registración Manual

Llamando esta función será posible registrar en cualquier momento la posición del dispositivo. Es buen uso actualizar la posición al momento en que pone utilizas la aplicación pero nada niega que siendo actualizada más frecuentemente así que pueda darte una geolocalización más precisa.

RegisterCurrentPosition()

RegisterCurrentPosition(options)

Ejemplo:

Puship.Common.RegisterCurrentPosition(
	{
    //callMinutes: 1,
    //enableHighAccuracy: true,
    //minimumAccuracy: 50, // Excluye las posiciones con esmera relevada < 50 metros 
	successCallback: function (regresult){
		navigator.notification.alert("Position registration done");
	},
	failCallback: function (regresult){
		navigator.notification.alert("Position registration error: "+ regresult);
	}
});

La opción callMinutes permite de impostar el tiempo entre una llamada y las sucesivas al server de puship, para optimizar el utilizo de la banda. No es posible impostar un valor menor de 1 minuto.
La opción enableHighAccuracy permite de reforzar el utilizo del GPS.
La opción minimumAccuracy permite de excluye la posiciones relevantes con una atención relevada menor a la que impostaste. Si la esmera relevada es anulada la posición nunca será eliminada

 
El parámetro de retorno watchId tendrás que ser utilizado para arrestar la registración automática de la posición por el método ClearWatch.

Atención: algunas versiones de los sistemas operativos deshabilitan by design la geolocalización cuando el device viene bloqueado o se sale de la aplicación.

 

Des habilitación Registración Automática

Llamando esta función será posible deshabilitar la registración automática de la posición del device.

ClearWatch(watchId)

Siguiendo encontraras un ejemplo:

Puship.Common.ClearWatch(watchId);

La opción watchId contiene el identificativo de el watcher creado.

CANCELAR LA REGISTRACION DE UN DEVICE

Alguna vez puede ser necesario cancelar la registracion del dispositivo, y para hacerlo es suficiente uno de los siguientes métodos:

UnRegister()

UnRegister(callbackSuccess)

UnRegister(callbackSuccess, callbackFail)

Ejemplo:

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