Java

Utilizzando Java è possibile integrarsi con Puship in pochi semplici passi, è sufficiente inserire nel proprio progetto il file PushipApi.jar, impostare l’AppId dell’ applicazione con la quale si desidera interagire, lo Username e la Password del vostro profilo Puship, l’EnableDebug(default false), ed il timezone per la conversione delle date.

Credentials cr = new Credentials("MRossi", "PassWord"); //Setta Username, Password e AppId 
CoreApi ca = new CoreApi("APKCbOd72fXKVUU", cr);

//ca.Binarysupport = false; //Da impostare solo quando si utilizza la libreria su Android
ca.EnableDebug = true; //Mostra Url, parametri dell'Url, Codice di Risposta, e la risposta dal Server

PushipUtil.SetTimeZone("Europe/Rome"); //Setta il Timezone desiderato per convertire le date provenienti da Puship

a questo punto è possibile iniziare ad effettuare le chiamate attraverso i seguenti metodi:

Lettura delle notifiche
Lettura delle notifiche per Device
Lettura delle App
Eliminazione di una notifica
Eliminazione dei device
Gestione dei Filtri
Lettura dei Device
Invio di una notifica
Invio di una notifica per Device

Lettura delle notifiche

La lettura delle notifiche può essere fatta utilizzando dei parametri, anche combinati tra loro. Permettendo così di recuperare ad esempio le push per una determinata piattaforma ed una specifica posizione.

Il metodo da utilizzare è: GetPushMessages(param)

I possibili parametri sono:

DeviceType int: Filtra le notifiche per piattaforma (parametro obbligatorio)

Limit int: Numero di record massimi ritornati nella chiamata (default 5)

Offset long: Record di partenza per la lettura paginata (default 0)

Tags array di stringhe: Filtra le notifiche per tag inviati

DeviceId string: Aggiunge ai risultati le notifiche inviate ad uno specifico device

Latitude double: Latitudine della posizione da filtrare

Longitude double: Longitudine della posizione da filtrare

IncludeParams boolean: True se si desidera includere i parametri della notifica (default false)

Il risultato è un array di oggetti contenente i seguenti attributi:

PushMessageId string: Id della notifica

Date datetime: Data e ora nel formato json

Message string: Testo della notifica

Params mappa di stringhe: Lista dei parametri, possibili Chiavi: Param1, Param2, Param3, Param4, Param5

Lettura delle notifiche per Piattaforma

Consente di recuperare le notifiche in base alla Piattaforma a cui sono state associate. E’ sufficiente impostare uno dei seguenti valori nel parametro DeviceType:

1 = Piattaforma Apple

2 = Piattaforma GCM

3 = Piattaforma WP7/8

4 = BlackBerry

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("DeviceType", "1"); //Filtro piattaforma Apple
JSONArray al = ca.GetPushMessages(map);

Lettura delle notifiche per Tag

Consente di filtrare le notifiche per tag a cui sono state associate. Per default, se non viene impostato nessun tag, vengono restituite tutte le notifiche, indipendentemente dai tag associati.

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("DeviceType", "1");
Set tagmaps = new HashSet();
tagmaps.add("Libra"); //Tag numero 1
tagmaps.add("Virgo"); //Tag numero 2
map.put("Tags", tagmaps);
JSONArray al = ca.GetPushMessages(map);

Lettura delle notifiche per Posizione

Consente di recuperare le notifiche in base all’area ad esse associate. Per default, se non viene impostata una posizione, vengono restituite tutte le notifiche indipendentemente dall’area associata.

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("DeviceType", "1");  
map.put("Latitude", "45.44085"); //latitudine al centro di Venezia
map.put("Longitude", "12.31552"); //longitudine al centro di Venezia
JSONArray al = ca.GetPushMessages(map);

Lettura delle notifiche con Parametri

Consente di recuperare le notifiche e i parametri associati. Di default i parametri non vengono inclusi per minimizzare la trasmissione dati.

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("DeviceType", "1");  
map.put("IncludeParams", "True");
JSONArray al = ca.GetPushMessages(map);

Lettura con aggiunta delle notifiche inviate singolarmente

Consente di aggiungere ai risultati dei precedenti filtri tutte le notifiche che il dispositivo ha ricevuto dal momento in cui è stato registrato.

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("DeviceType", "1");
map.put("DeviceId", "APKCbOd72fXKVUU_7a6ff1f023039299");
JSONArray al = ca.GetPushMessages(map);

Questa richiesta restituisce tutte le notifiche push inviate ai dispositivi Apple ed inoltre tutte le notifiche inviate al dispositivo con id APKCbOd72fXKVUU_7a6ff1f023039299.

Lettura di tutte le notifiche

Consente di recuperare tutte le notifiche inviate come vengono visualizzate sulla dashboard di Puship.

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("Limit", "10");
map.put("Offset", "0"); 
map.put("IncludeParams", "True");
JSONArray al = ca.GetAllPushMessages(map);

Questa richiesta restituisce tutte le notifiche push aggiungendo i parametri.

ATTENZIONE: Gli elementi dell’array restituito conterranno anche gli attributi booleani SentToAPNS, SentToBPNS, SentToMPNS, SentToGCM che identificano per quale piattaforma è stata inviata la notifica

Lettura delle notifiche per Device

Questa modalità permette di leggere le notifiche inviate ad un determinato device

Il metodo da utilizzare è: GetPushMessagesByDevice (param)

I possibili parametri sono:

DeviceId string: Id del Device per il quale si vogliono ottenere le notifiche (obbligatorio)

Limit int: Numero di record massimi restituiti dalla chiamata (default 5)

Offset long: Record di partenza per la lettura paginata (default 0)

IncludeParams boolean: True se si desidera includere i parametri della notifica (default false)

Il risultato è un array di oggetti contenente i seguenti attributi:

PushMessageId string: Id della notifica

Date datetime: Data e ora nel formato json

Message string: Testo della notifica

Params mappa di stringhe: Lista dei parametri, possibili Chiavi: Param1, Param2, Param3, Param4, Param5

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("DeviceType", "1");
map.put("DeviceId", "APKCbOd72fXKVUU_7a6ff1f023039299");
JSONArray al = ca.GetPushMessagesByDevice(map);

Lettura delle App

Questa modalità permette di recuperare la lista delle Applicazioni

Il metodo da utilizzare è: GetApps (param)

I possibili parametri sono:

Limit int: Numero di record massimi restituiti dalla chiamata (default 5)

Offset long: Record di partenza per la lettura paginata (default 0)

Il risultato è un array di oggetti contenente i seguenti attributi:

AccessCode string: Id dell’applicazione

Created datetime: Data e ora di creazione nel formato json

Updated datetime: Data e ora di ultimo aggiornamento nel formato json

Name string: Nome dell’applicazione

Development boolean: True se l’APNS è configurato per lo sviluppo, False se è configurato per produzione

EnableAPNS boolean: True se l’APNS è configurato

EnableBPNS boolean: True se l’BPNS è configurato

EnableMPNS boolean: True se l’MPNS è configurato

EnableGCM boolean: True se il GCM è configurato

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("Limit", "15");
map.put("Offset", "0");
JSONArray al = ca.GetApps(map);

ATTENZIONE: Questa chiamata non necessita del settaggio dell’AppId (new CoreApi(null, cr);)

Eliminazione di una notifica

Permette di eliminare una notifica in base al suo Id.

Il metodo da utilizzare è: DeletePushMessage (param)

I possibili parametri sono:

PushMessageId string: Id della notifica da eliminare (obbligatorio)

Il risultato è un oggetto contenente i seguenti attributi:

Error boolean: Ritorna True in caso di errore

Message string: Messaggio relativo all’errore o all’azione appena conclusa

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("PushMessageId", "APKCbOd72fXKVUU_635192605191400000"); // Id della notifica da eliminare
JSONObject al = ca.DeletePushMessage(map);

Eliminazione dei device

Permette di eliminare una lista di device in base al loro Id.

Il metodo da utilizzare è: DeleteDevices (param)

I possibili parametri sono:

Devices array di stringhe: Lista degli id dei device da eliminare (obbligatorio)

Il risultato è un oggetto contenente i seguenti attributi:

Error boolean: Ritorna True in caso di errore

Message string: Messaggio relativo all’errore o all’azione appena conclusa

StringParam1 string: Se l’azione viene completata con successo contiene il numero dei device eliminati

Esempio:

HashMap<string, object=""> map =  new HashMap<string, object="">();

Set devicetodelete = new HashSet();
devicetodelete.add("jS0oE8PtHcVerde_05CD0C12-35A7-4123-8E9F-AA74FF418A18"); // Id del device da eliminare
devicetodelete.add("jS0oE8PtHcVerde_0FDFED66-3CD6-4208-BAA1-90968D1AFA01"); 
devicetodelete.add("jS0oE8PtHcVerde_7a6ff0f023039299");
map.put("Devices", devicetodelete);
JSONObject al = ca.DeleteDevices(map);

Gestione dei Filtri

Questa sezione spiega come poter interagire con i filtri

Lettura dei Filtri dell’applicazione

Questo metodo permette di leggere i Filtri associati all’applicazione.

Il metodo da utilizzare è: GetAppTagFilters (param)

I possibili parametri sono:

ReturnHystory boolean: Se impostato a True la lettura restituisce anche i filtri utilizzati in passato ma che non sono più associati a nessun device (default false).

Il risultato è un array di stringhe.

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("ReturnHistory", "True");
JSONArray al = ca.GetAppTagFilters(map);

Aggiunta di un Filtro al device

Questo metodo permette di aggiungere un filtro ad un device.

Il metodo da utilizzare è: AddTagFilter (param)

I possibili parametri sono:

DeviceId string: Id del Device per il quale si vuole aggiungere il Tag (obbligatorio)

Tag string: Tag da aggiungere al device (obbligatorio)

Il risultato è un oggetto contenente i seguenti attributi:

Error boolean: Ritorna True in caso di errore

Message string: Messaggio relativo all’errore o all’azione appena conclusa

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("DeviceId", "jS0oE8PtHcVerde_E57F63B1-E43F-48F0-8A08-149F7168A1DE");
map.put("Tag", "Libra");	//Imposta il tag che vuoi aggiungere
JSONObject al = ca.AddTagFilter(map);

Rimozione di un Filtro dal device

Questo metodo permette di rimuovere un filtro da un device.

Il metodo da utilizzare è: RemoveTagFilter (param)

I possibili parametri sono:

DeviceId string: Id del Device per il quale si vuole aggiungere il Tag (obbligatorio)

Tag string: Tag che si vuole rimuovere dal device (obbligatorio)

Il risultato è un oggetto contenente i seguenti attributi:

Error boolean: Ritorna True in caso di errore

Message string: Messaggio relativo all’errore o all’azione appena conclusa

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("DeviceId", "jS0oE8PtHcVerde_E57F63B1-E43F-48F0-8A08-149F7168A1DE");
map.put("Tag", "Libra");	//Imposta il tag che vuoi rimuovere
JSONObject al = ca.RemoveTagFilter(map);

Rimozione di tutti i Filtri del device

Questo metodo permette di rimuovere tutti filtri da un device.

Il metodo da utilizzare è: CleanTagFilter (param)

I possibili parametri sono:

DeviceId string: Id del Device per il quale si vuole aggiungere il Tag (obbligatorio)

Il risultato è un oggetto contenente i seguenti attributi:

Error boolean: Ritorna True in caso di errore

Message string: Messaggio relativo all’errore o all’azione appena conclusa

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("DeviceId", "jS0oE8PtHcVerde_E57F63B1-E43F-48F0-8A08-149F7168A1DE"); //Rimuove tutti i tag collegati a questo device
JSONObject al = ca.CleanTagFilter(map);

Lettura dei Device

La lettura dei device registrati può essere filtrata utilizzando svariati parametri, anche combinati fra loro. Per esempio è possibile recuperare i device di una determinata piattaforma presenti in una specifica area.

Il metodo da utilizzare è: GetDevices (param)

I possibili parametri sono:

DeviceType int: Filtra le notifiche per piattaforma (obbligatorio)

Limit int: Numero di record massimi restituiti dalla chiamata (default 5)

Offset long: Record di partenza per la lettura paginata (default 0)

Tags array di stringhe: Filtra le notifiche per tag inviati

Expired boolean: Restituisce anche i device con Token scaduto

Point Example

P1Latitude double: Latitudine del Punto 1 della posizione da filtrare

P1Longitude double: Longitudine del Punto 1 della posizione da filtrare

P2Latitude double: Latitudine del Punto 2 della posizione da filtrare

P2Longitude double: Longitudine del Punto 2 della posizione da filtrare

LastPositionDate time: Data in UTC dalla quale considerare la registrazione della posizione

LastPositionNumber int: Numero delle ultime posizioni da tenere in considerazione (default infinite)

Il risultato è un array di oggetti contenente i seguenti attributi:

DeviceId string: Id del device

Expired boolean: True se il token è scaduto

DeviceType int: Piattaforma del device

Created datetime: Data e Ora di prima registrazione del device in formato json

Updated datetime: Data e Ora di aggiornamento della registrazione in formato json

Lettura semplice dei Device

La lettura semplice restituisce tutti i device registrati indipendentemente da qualsiasi filtro e piattaforma.

Di seguito trovate un esempio:

JSONArray al = ca.GetDevices();

Lettura dei Device per Piattaforma

Consente di filtrare i device in base ad una piattaforma. E’ sufficiente impostare uno dei seguenti valori nel parametro DeviceType:

1 = Piattaforma Apple

2 = Piattaforma Android

3 = Piattaforma Windows

4 = BlackBerry

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("DeviceType", "1"); // Filtro per piattaforma Apple
JSONArray al = ca.GetDevices(map);

Lettura dei Device per Tag

Consente di filtrare i device in base ad uno o più Tag.

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
Set tagmaps = new HashSet();
tagmaps.add("Libra"); //Tag numero 1
tagmaps.add("Virgo"); //Tag numero 2
map.put("Tags", tagmaps);
JSONArray al = ca.GetDevices(map);

Lettura dei Device per Area

Consente di filtrare i device in base alle posizione registrate.

Esempio:

HashMap<string, object=""> map = new HashMap<string, object="">();
map.put("P1Latitude", "40.42163694648697"); // Impostiamo l'area di Venezia
map.put("P1Longitude", "10.299156188964844");
map.put("P2Latitude", "47.45030563100575");
map.put("P2Longitude", "15.368927001953125");
map.put("LastPositionNumber", "5"); // Vogliamo che la registrazione nell'area di Venezia sia stata effettuata solamente tra le ultime 5 registrazioni
Calendar c = Calendar.getInstance();
c.set(2020, 5, 6, 0, 0,0); // Giugno, 07, 2020
map.put("LastPositionDate", c.getTime()); // Mostra i device registrati dopo la data inserita
JSONArray al = ca.GetDevices(map);

Invio di una notifica

L’invio di una notifica può essere effettuato utilizzando svariati parametri, anche combinati fra loro. Per esempio è possibile inviare una notifica per una determinata piattaforma, una specifica area ed un determinato Tag.

Il metodo da utilizzare è: SendPushMessage (param)

I possibili parametri sono:

SendIOS boolean: Invia la notifica alla piattaforma IOS (default false)

SendAndroid boolean: Invia la notifica alla piattaforma Android (default false)

SendBB boolean: Invia la notifica alla piattaforma BlackBerry (default false)

SendWP boolean: Invia la notifica alla piattaforma Wp7/8 (default false)

Message string: Il messaggio da inviare

Badge int: Badge associato alla notifica (default 1)

Push boolean: Imposta l’invio(true) o il solo salvataggio(false) della notifica (default true)

Sound string: Nome del file da riprodurre all’arrivo della notifica (default Default)

Tags Array di stringhe: Filtra le notifiche per Tag inviati

Point Example

P1Latitude double: Latitudine del Punto 1 della posizione da filtrare

P1Longitude double: Longitudine del Punto 1 della posizione da filtrare

P2Latitude double: Latitudine del Punto 2 della posizione da filtrare

P2Longitude double: Longitudine del Punto 2 della posizione da filtrare

LastPositionDate time: Data in UTC dalla quale considerare la registrazione della posizione

LastPositionNumber int: Numero delle ultime posizioni da tenere in considerazione (default infinite)

Params mappa di stringhe: Mappa di massimo 5 elementi per inserire parametri generici

Il risultato è un oggetto contenente i seguenti attributi:

Error boolean: Ritorna True in caso di errore

Message string: Messaggio relativo all’errore o all’azione appena conclusa

StringParam1 string: Se l’azione viene completata con successo contiene l’ID della notifica appena creata

Invio di una notifica per Piattaforma

Consente di inviare o salvare una notifica in base alle piattaforme. E’ necessario impostare almeno uno dei seguenti parametri a true:

SendIOS

SendAndroid

SendBB

SendWP

Esempio:

HashMap<string, object=""> map =  new HashMap<string, object="">();
map.put("Message", "Push inviata a tutti i device WindowsPhone!");
map.put("SendIOS", "False");
map.put("SendAndroid", "False");
map.put("SendBB", "False");
map.put("SendWP", "True");
JSONArray al = ca.SendPushMessage(map);

Invio di una notifica per Tag

Consente di inviare o salvare una notifica in base ai Tag per i quali il device si è registrato.

Esempio:

HashMap<string, object=""> map =  new HashMap<string, object="">();
map.put("Message", "Push inviata ai device Android associati ai Tag Virgo o Libra!");
map.put("SendIOS", "False");
map.put("SendAndroid", "True");
map.put("SendBB", "False");
map.put("SendWP", "False");
Set tagmaps = new HashSet();
tagmaps.add("Libra"); //Tag numero 1
tagmaps.add("Virgo"); //Tag numero 2
map.put("Tags", tagmaps);
JSONArray al = ca.SendPushMessage(map);

Invio di una notifica per Area

Consente di inviare o salvare una notifica in base alle posizioni nelle quali il device si è registrato.

Esempio:

HashMap<string, object=""> map =  new HashMap<string, object="">();
map.put("Message", "Push inviata ai device Android registrati a Venezia negli ultimi due mesi");
map.put("SendIOS", "False");
map.put("SendAndroid", "True");
map.put("SendBB", "False");
map.put("SendWP", "False");
map.put("P1Latitude", "40.42163694648697"); // Impostiamo l'area di Venezia
map.put("P1Longitude", "10.299156188964844");
map.put("P2Latitude", "47.45030563100575");
map.put("P2Longitude", "15.36892001953125")
Calendar c = Calendar.getInstance();
c.set(2014, 5, 6, 0, 0,0); // Giugno, 07, 2014
map.put("LastPositionDate", c.getTime());
JSONArray al = ca.SendPushMessage(map);

Invio di una notifica con Parametri

Consente di inviare o salvare una notifica con dei parametri generici.

Esempio:

HashMap<string, object=""> map =  new HashMap<string, object="">();
map.put("Message", "Push inviata ai device Android con l'aggiunta di 5 parametri generici");
map.put("SendIOS", "False");
map.put("SendAndroid", "True");
map.put("SendBB", "False");
map.put("SendWP", "False");
HashMap<string, object=""> params =  new HashMap<string, object="">(); // Puoi inserire Testo semplice, urls, pagine da aprire...
params.put("Param1", "Param number 1");
params.put("Param2", "ttps://www.facebook.com/OfficialPuship");
params.put("Param3", "index.html");
params.put("Param4", "122.45");
params.put("Param5", "Special chars:  '%1234567890\"!£$%&/()=?^ιθ@#°§ω-,'"); // Max 5 parametri, i successivi sono ignorati
map.put("Params", params);
JSONArray al = ca.SendPushMessage(map);

Invio di una notifica per Device

Permette di inviare o associare una notifica ad uno o più device in base al loro Id.

Il metodo da utilizzare è: SendPushMessageByDevice (param)

I possibili parametri sono:

Message string: Il messaggio da inviare

Badge int: Badge associato alla notifica (default 1)

Push boolean: Imposta l’invio(true) o il solo salvataggio(false) della notifica (default true)

Sound string: Nome del file da riprodurre all’arrivo della notifica (default Default)

Devices array di stringhe: Id dei device ai quali inviare la notifica (almeno un elemento obbligatorio)

Params mappa di stringhe: Mappa di massimo 5 elementi per inserire parametri generici

Il risultato è un oggetto contenente i seguenti attributi:

Error boolean: Ritorna True in caso di errore

Message string: Messaggio relativo all’errore o all’azione appena conclusa

StringParam1 string: Se l’azione viene completata con successo contiene l’ID della notifica appena creata

Esempio:

HashMap<string, object=""> map =  new HashMap<string, object="">();
map.put("Message", "Push inviata a due specifici device");
Set devicetosend = new HashSet();
devicetosend.add("APKCbOd72fXKVUU_b87389c9-5e86-45cd-88e0-9cc239643faf"); // Device numero 1 (microsoft device)
devicetosend.add("APKCbOd72fXKVUU_7a6ff0f023039299"); // Device numero 2 (android device)
map.put("Devices", devicetosend);
JSONArray al = ca.SendPushMessageByDevice(map);

Scaricando il file PushipApi.jar trovarei all’interno anche un file di esempio per la configurazione e le chiamate ai vari metodi.

Scarica PushipApi.jar + Esempio

Attenzione: La libreria non è supportata da versioni di Java inferiori alla 1.6.