Notifiche e endpoint pubblici di OpenPlatform

Oltre all’avvio e alla verifica, OpenPlatform ha alcuni endpoint per le applicazioni e per altri sistemi. Si trovano in controllers/verify.js, controllers/api.js e controllers/socket.js.

Inviare una notifica

La risposta della verifica contiene notify, un indirizzo della forma <platform url>/notify/?token=<checksum of user and application>, quando l’utente accetta le notifiche. L’applicazione vi invia un POST con l’intestazione x-token e un corpo JSON:

Campo	Significato
body	il testo della notifica
path	il percorso all’interno dell’applicazione che la notifica apre
icon, color	facoltativi: sostituiscono l’icona e il colore dell’applicazione

Il valore di x-token è il token di notifica che OpenPlatform deriva per quell’utente e quell’applicazione: l’MD5 dell’indirizzo di notifica con il sale del reqtoken dell’applicazione, e l’MD5 di quel risultato con il sale del suo restoken (FUNC.makenotify in definitions/func.js). Entrambi i segreti sono gli stessi che l’applicazione condivide per l’avvio (registrare un’app).

OpenPlatform risponde Invalid token quando il checksum o l’intestazione non corrispondono, e Not allowed notifications quando l’utente o l’applicazione non le accetta. Controlla anche gli indirizzi consentiti dell’applicazione e che l’utente sia confermato, abilitato e attivo. Quando tutto è a posto:

1. memorizza la notifica (tabella tbl_notification) e aumenta il contatore dei non letti dell’utente;
2. aggiorna le sessioni di quell’utente aperte nel portale, così il contatore compare subito;
3. pubblica Notifications.create tramite TMS quando l’impostazione $tms è attiva;
4. restituisce l’identificativo della notifica.

Per gli utenti offline con notifiche non lette, un job di servizio invia un riepilogo via e-mail ("Unread notifications") quando le impostazioni della posta sono configurate, al massimo una volta ogni tre giorni per utente (definitions/init.js).

L’API degli utenti (un token)

GET /users/ restituisce i gruppi e gli utenti della piattaforma come JSON. È disabilitata finché non sono impostati allow_token e token. Il chiamante invia il token come parametro di query token o come intestazione x-token; i ripetuti tentativi errati vengono bloccati. Gli utenti arrivano senza segreti: identificativo, riferimento, lingua, genere, foto (un indirizzo assoluto), nome, e-mail, colore, preferenze, flag (sa, isdisabled, isinactive, isonline), date e gli id dei loro gruppi.

Caricare un’immagine

POST /upload/base64/ (fino a 2 MB) accetta un corpo JSON con il nome del file e file come data URI, e solo JPEG. Richiede un utente con accesso o il token di query dell’impostazione servicetoken (vedi impostazioni e database per sapere da dove viene quella chiave). L’immagine è memorizzata nell’archivio di file files e la risposta è il suo indirizzo, /files/<id and checksum>.jpg; l’indirizzo funziona solo con il checksum.

Più istanze: il socket di sincronizzazione

SOCKET /sync/ collega istanze di OpenPlatform. Un client viene accettato quando l’impostazione sync è attiva e il token della query è uguale a sync_token; qualsiasi altro client viene chiuso con il codice 4001 mezzo secondo dopo l’apertura. I messaggi di un client confermato vengono inoltrati agli altri e, mentre un client confermato si sta riconnettendo, i messaggi sono messi in coda per un massimo di dieci secondi.