Php

Utilizzando Php è possibile integrarsi con Puship in pochi semplici passi, è sufficiente inserire nel proprio progetto il file PushipApi.php, 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.

<?php
date_default_timezone_set('Europe/Rome'); //Setta il Timezone desiderato per convertire le date provenienti da Puship

require_once('PushipApi.php');

$config = array();
$config['AppId'] = 'APKCbOd72fXKVUU';
$config['Username'] = 'MRossi';
$config['Password'] = 'PassWord';

$puship = new PushipApi($config);

$puship -> EnableDebug = true; //Mostra URL, parametri dell'URL, e risposta dal Server

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 con alcuni 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

Quest’ultima 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 Android

3 = Piattaforma Windows

4 = BlackBerry

Esempio:

<?php
$param = array();
$param['DeviceType'] = '1'; // Filtro per Piattaforma Apple
$puship->GetPushMessages($param);

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:

<?php
$param = array();
$param['DeviceType'] = '1';
$tagstosend = array();
$tagstosend[0]='Virgo'; //Tag numero 1
$tagstosend[1]='Libra'; //Tag numero 2
$param['Tags'] = $tagstosend;
$puship->GetPushMessages($param);

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:

<?php
$param = array();
$param['DeviceType'] = '1';
$param['Latitude'] = '45.44085'; // Latitudine al centro di Venezia
$param['Longitude'] = '12.31552'; // Longitudine al centro di Venezia
$puship->GetPushMessages($param);

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:

<?php
$param = array();
$param['DeviceType'] = '1';
$param['IncludeParams'] = 'True';
$puship->GetPushMessages($param);

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:

<?php
$param = array();
$param['DeviceType'] = '1';
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';  
$puship->GetPushMessages($param);

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:

<?php
$param = array();
$param['DeviceType'] = '1';
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';  
$puship->GetPushMessages($param);

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:

<?php
$param = array();
$param['DeviceType'] = '1';
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';  
$puship->GetPushMessagesByDevice($param);

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:

<?php
$param = array();
$param['Limit'] = '15';
$param['Offset'] = '0';
$puship->GetApps($param);

ATTENZIONE: Questa chiamata non necessita del settaggio dell’AppId ($config[‘AppId’] = ‘APKCbOd72fXKVUU’;)

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:

<?php
$pushparam = array();
$pushparam['PushMessageId'] = 'APKCbOd72fXKVUU_635192605191400000'; // Id della notifica da eliminare
$puship->DeletePushMessage($pushparam);

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:

<?php
$pushparam = array();
$devicetodelete = array();
$devicetodelete[0] = 'jS0oE8PtHcVerde_05CD0C12-35A7-4123-8E9F-AA74FF418A18'; //id del device da eliminare
$devicetodelete[1] = 'jS0oE8PtHcVerde_0FDFED66-3CD6-4208-BAA1-90968D1AFA01'; 
$devicetodelete[2] = 'jS0oE8PtHcVerde_7a6ff0f023039299';
$pushparam['Devices'] = $devicetodelete;
$puship->DeleteDevices($pushparam);

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:

<?php
$tagparam = array();
$tagparam['ReturnHystory']='True';
$puship->GetAppTagFilters($tagparam);

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:

<?php
$param = array();
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';
$param['Tag'] = 'Libra'; //Imposta il tag che vuoi aggiungere
$puship->AddTagFilter($param);

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:

<?php
$param = array();
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';
$param['Tag'] = 'Libra';	//Imposta il tag che vuoi rimuovere
$puship->RemoveTagFilter($param);

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:

<?php
$param = array();
$param['DeviceId'] = 'APKCbOd72fXKVUU_7a6ff1f023039299';
$puship->CleanTagFilter($param);

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

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:

<?php
$puship->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:

<?php
$param = array();
$param['DeviceType'] = '1'; // Filtro per Piattaforma Apple
$puship->GetDevices($param);

Lettura dei Device per Tag

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

Esempio:

<?php
$param = array();
$tagstosend = array();
$tagstosend[0]='Virgo'; //Tag numero 1
$tagstosend[1]='Libra'; //Tag numero 2
$param['Tags'] = $tagstosend;
$puship->GetDevices($param);

Lettura dei Device per Area

Consente di filtrare i device in base alle posizione registrate.

Esempio:

<?php
$param = array();
$param['P1Latitude'] = '40.42163694648697'; //Impostiamo l'area di Venezia
$param['P1Longitude'] = '10.299156188964844';
$param['P2Latitude'] = '47.45030563100575';
$param['P2Longitude'] = '15.368927001953125';
$param['LastPositionNumber'] = '5'; // Vogliamo che la registrazione nell'area di Venezia sia stata effettuata solamente tra le ultime 5 registrazioni
$param['LastPositionDate'] = strtotime('-10 days UTC'); // La registrazione non deve essere più vecchia di 10 giorni
$puship->GetDevices($param);

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:

<?php
$push = array();
$push['Message'] = 'Push inviata a tutti i device Apple e Android!';
$push['SendIOS'] = 'True';
$push['SendAndroid'] = 'True';
$push['SendBB'] = 'False';
$push['SendWP'] = 'False';
$puship->SendPushMessage($push);

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:

<?php
$param = array();
$param['Message'] = 'Push inviata ai device Android associati ai Tag Virgo o Libra!';
$param['SendIOS'] = 'False';
$param['SendAndroid'] = 'True';
$param['SendBB'] = 'False';
$param['SendWP'] = 'False';
$tagstosend = array();
$tagstosend[0]='Virgo'; //Tag number 1
$tagstosend[1]='Libra'; //Tag number 2
$param['Tags'] = $tagstosend;
$puship->SendPushMessage($param);

Invio di una notifica per Area

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

Esempio:

<?php
$param = array();
$param['Message'] = 'Push inviata ai device Android registrati a Venezia negli ultimi due mesi';
$param['SendIOS'] = 'False';
$param['SendAndroid'] = 'True';
$param['SendBB'] = 'False';
$param['SendWP'] = 'False';
$param['P1Latitude'] = '40.42163694648697'; //Impostiamo l'area di Venezia
$param['P1Longitude'] = '10.299156188964844';
$param['P2Latitude'] = '47.45030563100575';
$param['P2Longitude'] = '15.368927001953125';
$param['LastPositionDate'] = strtotime('-2 months UTC'); // La registrazione non deve essere piu vecchia di 2 mesi
$puship->SendPushMessage($param);

Invio di una notifica con Parametri

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

Esempio:

<?php
$param = array();
$param['Message'] = 'Push inviata ai device Android con l'aggiunta di 5 parametri generici';
$param['SendIOS'] = 'False';
$param['SendAndroid'] = 'True';
$param['SendBB'] = 'False';
$param['SendWP'] = 'False';
$params = array(); // Puoi inserire Testo semplice, urls, pagine da aprire...
$params['Param1'] = 'Param number 1';
$params['Param2'] = 'https://www.facebook.com/OfficialPuship';
$params['Param3'] = 'index.html';
$params['Param4'] = '122.45';
$params['Param5'] = 'Special chars:  \'%1234567890"!£$%&/()=?^éè@#°§ù-,\'';   //Max 5 parametri, i successivi sono ignorati
$push['Params'] = $params;
$puship->SendPushMessage($param);

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:

<?php
$push = array();
$push['Message'] = 'Push inviata a due specifici device!';
$devicestosend = array();
$devicestosend[0] = 'APKCbOd72fXKVUU_b87389c9-5e86-45cd-88e0-9cc239643faf'; //Device numero 1 (microsoft device)
$devicestosend[1] = 'APKCbOd72fXKVUU_7a6ff0f023039299'; //Device numero 2 (android device)
$push['Devices'] = $devicestosend;
$puship->SendPushMessageByDevice($push);

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

Scarica PushipApi.php + Esempio