L'approccio WebSocket consente uno scambio bidirezione real-time di messaggi tra i vostri client, che siano Web, Android, iOS o altro.
Per facilitare questo meccanismo essitono varie Client SDK che potrete utilizzare in maniera molto semplice ed in questa guida ne vengono spiegate tutte le funzionalita'.
Prima di iniziare bisogna definire il concetto di "topic", una sorta di canale con cui dare una logica ed organizzazione ai messaggi scambiati ed archiviati sul nostro cloud.
Ad esempio, in un app di ristorazione, i topic potrebbero essere i "tavoli", "ordini" o "piatti"; mentre in un instant messaging i topic sono le vere e proprie room di discussione.
Nell'approccio WebSocket ogni client puo' decidere di sottoscriversi o no ad uno o piu' topic in ogni momento e non e' necessario definire questi valori a priori.
La sottoscrizione effettuata con il comando di subscribe permette on-demand di generare il topic e di ricevere in real-time tutti i messaggi indirizzati verso quel topic dai vari client.
Esistono al momento 3 tipi di topic:
@
e il subscribe su questo topic necessita di un webhook di autenticazione.!<socket_id>
, ogni client connesso ad Xserv ha il suo e serve ad inviare un messaggio diretto one-to-one.Nella creazione dei topic, nel nome sono ammessi tutti i caratteri ad esclusione del carattere !
come primo carattere, utilizzato per il messaging one-to-one.
Tutti i topic che hanno come prefisso nel nome il carattere @
vengono riconosciuti e gestiti come topic privati,
quindi richiedono una fase di autenticazione in fase di subscribe.
Esiste un topic privato di default @guest
dove ogni utente puo' entrare con un user del tipo guest_%d
e pass guest
.
Questo permette sia di effettuare dei test che ti poter avere tutti i vataggi di un topic privato senza implementare o gestire le utenze.
Create a FREE account, create your first application and make a note of her app_id
.
Next you need add a client library in your project, we have several SDK such as Android, iOS, JavaScript, etc.
GitHub repo
https://github.com/xserv/xserv-js
Include jQuery and Xserv library in your page:
<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="https://mobile-italia.com/xserv/xserv.min.js"></script>
GitHub repo
https://github.com/xserv/xserv-android
Add internet permission to you AndroidManifest.xml
:
<uses-permission android:name="android.permission.INTERNET" />
Add as a dependency to your build.gradle
:
dependencies {
...
compile(group: 'com.mi.xserv', name: 'xserv-android', version: '+', ext: 'aar', classifier: '')
}
GitHub repo
https://github.com/xserv/xserv-ios
To integrate Xserv into your Xcode project using CocoaPods, specify it in your Podfile
:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
pod 'Xserv'
Il primo passo dopo la configurazione del progetto e' la definizione di un connettore Xserv. Con esso si puo' stabilire una connessione bidirezionale real-time per inviare e ricevere messaggi tra i vostri client.
Per prima cosa inizializzare un oggetto Xserv
.
var xserv = new Xserv(app_id);
public class MainActivity extends AppCompatActivity implements OnXservEventListener {
private Xserv mXserv;
@Override
protected void onCreate(Bundle savedInstanceState) {
...
mXserv = new Xserv(app_id);
mXserv.setOnEventListener(this);
...
}
...
}
@interface MyViewController () <XservDelegate>
@property (nonatomic, strong) Xserv *xserv;
@end
@implementation MyViewController
-(void) viewDidLoad {
...
self.xserv = [[Xserv alloc] initWithAppId:app_id];
self.xserv.delegate = self;
...
}
...
@end
app_id
String - The globally unique identifier of your application. It can be found within the Xserv dashboard.Per stabilire l'effettiva connessione bisogna eseguire il seguente comando.
E' possibile effetture un qualsiasi comando solo dopo che il connettore ha effettuato una open connection (vedere il prossimo punto eventi di connessione).
xserv.connect();
mXserv.connect();
[self.xserv connect];
NOTA: Se si perde la connessione il connettore tenta automaticamente una riconnessione ogni 5 secondi. Se si chiama manualmente una disconnect allora la rinonnessione automatica e' inibita fino al prossimo comando di connect.
E' anche possibile eseguire una disconnessione dal servizio.
xserv.disconnect();
NOTA: La connessione e' automaticamente chiusa quando si naviga in un altra pagina web o si chiude il browser.
mXserv.disconnect();
[self.xserv disconnect];
Uno degli aspetti piu' importante e' la ricezione di informazioni dal server che vanno dai semplici eventi di connessione ai messaggi (scambiati tra i client) e ai risultati di operazioni effetuate (subscribe, unsubscribe, ecc). La cui descrizione avviene nelle sezioni successive della guida.
E' molto importante ricevere informazioni sullo stato della connessione al servizio. La fase di connection_open, ad esempio, permette di poter sapere quando la connessione e' stabilita e poter inviare tutti gli altri comandi sulla socket.
xserv.addEventListener("connection_open", function() {
...
});
xserv.addEventListener("connection_close", function(event) {
...
});
xserv.addEventListener("connection_error", function(event) {
...
});
@Override
public void OnOpenConnection() {
...
}
@Override
public void OnCloseConnection(Exception e) {
...
}
@Override
public void OnErrorConnection(Exception e) {
...
}
-(void) didOpenConnection {
...
}
-(void) didCloseConnection:(NSError *)reason {
...
}
-(void) didErrorConnection:(NSError *)reason {
...
}
Con il seguente codice e' possibile ricevere tutti i messaggi pubblicati sui topic per cui il client ha effettuato precedentemente una subscribe.
xserv.addEventListener("messages", function(json) {
...
});
@Override
public void OnReceiveMessages(JSONObject json) {
...
}
-(void) didReceiveMessages:(NSDictionary *)json {
...
}
id
String - The message identifier assigned by Xserv.topic
String - The name of the topic.data
(String | JSON) - The data of the message.user
String - The username is present only in a private topic.socket_id
String - The session identifier of client socket that sent the message.device_token
String - Device token for mobile notification.timestamp
Integer - Timestamp assigned by Xserv.Con il seguente codice e' possibile ricevere tutti gli esiti delle operazioni effettuate dal client come ad esempio i comandi di subscribe, unsubscribe, publish, etc. nonche' gli eventi di join e leave degli utenti entrati o usciti da un topic privato.
xserv.addEventListener("operations", function(json) {
...
});
@Override
public void OnReceiveOperations(JSONObject json) {
...
}
-(void) didReceiveOperations:(NSDictionary *)json {
...
}
uuid
String - The universally unique identifier of the operation.rc
Integer - Result code of the operation.descr
String - A possible description of the result.op
Integer - The identifier code of the operation.name
String - The name of the operation.topic
String - The name of the topic. In some cases it does not exist.data
JSON - A possible data of the operation response.timestamp
Integer - Timestamp assigned by Xserv.Ecco il comando per permettere al proprio client di sottoscriversi alla ricezione di messaggi su un topic pubblico.
var uuid = xserv.subscribe(topic);
String uuid = mXserv.subscribe(topic);
NSString *uuid = [self.xserv subscribeOnTopic:topic];
topic
String - The name of the topic to subscribe to.Il comando per permettere al proprio client di sottoscriversi alla ricezione di messaggi su un topic privato e' identico alla normale subscribe ma in piu' e' necessario utilizzare il meccanismo di webhook per garantire l'accesso dell'utente e validare eventuali suoi dati applicativi.
La subscribe al topic privato permette inoltre di ricevere le notifiche di join/leave di tutte le connessioni client.
L'endpoint e' una semplice HTTP API che potete realizzare voi su di un vostro server dove avete gia' i dati delle vostre utenze (vedere le specidiche del formato della response nell'apposita pagina) o potete usare i nostri servizi per gestire le utenze e quindi l'accesso ai vari topic privati.
var auth = {
endpoint: "http://yourserver/auth", // remove key to use xserv auth
headers: {
}
params: {
"user": "test",
"pass": "test"
}
};
var uuid = xserv.subscribe(topic, auth);
JSONObject auth = new JSONObject();
try {
auth.put("endpoint", "http://yourserver/auth"); // remove key to use xserv auth
JSONObject headers = new JSONObject();
auth.put("headers", headers);
JSONObject params = new JSONObject();
params.put("user", "test");
params.put("pass", "test");
auth.put("params", params);
} catch (JSONException ignored) {
}
String uuid = mXserv.subscribe(topic, auth);
NSDictionary *auth = @{
@"endpoint": @"http://yourserver/auth", // remove key to use xserv auth
@"headers": @{
},
@"params": @{
@"user": @"test",
@"pass": @"test"
}
};
NSString *uuid = [self.xserv subscribeOnTopic:topic withAuth:auth];
topic
String - The name of the topic to subscribe to. Since it is a private topic the name must be prefixed with @
.auth
JSON
endpoint
String [optional] - HTTP API Authentication.headers
Dict [optional] - An object of additional header key/value pairs to send along with request.params
Dict - An object of data key/value pairs to send along with request (ex. user, pass, etc).NOTA: Se il campo endpoint non e' presente il client utilizzera' il servizio di autenticazione di Xserv che ha come soli parametri user e pass.
Ecco il comando per rimuovere il proprio client dalla ricezione di messaggi su un topic sia pubblico che privato.
var uuid = xserv.unsubscribe(topic);
String uuid = mXserv.unsubscribe(topic);
NSString *uuid = [self.xserv unsubscribeOnTopic:topic];
topic
String - The name of the topic to unsubscribe from.Questo comando consente di inviare dati one-to-many su un determinato topic. Se si e' subscribed sul topic anche chi invia l'evento
ricevera' il messaggio.
Per inviare un messaggio one-to-one il campo topic deve essere composto dal
socket_id
del client destinataro preceduto dal carattere !
.
var uuid = xserv.publish(topic, data);
String uuid = mXserv.publish(topic, data);
NSString *uuid = [self.xserv publish:data onTopic:topic];
topic
String - The name of the topic that the message is to be published on.
A client-to-client message must have a name formed by socket_id
prefixed with !
.data
(String | JSON) - The data to be sent.Questo comando consente di modificare un messaggio gia' archiviato in un topic attraverso il suo object_id
.
I client sottoscritti sul topic riceveranno nuovamente il messaggio con i nuovi dati ma stesso id.
var uuid = xserv.update(topic, object_id, data);
String uuid = mXserv.update(topic, object_id, data);
NSString *uuid = [self.xserv update:data withObjectId:object_id onTopic:topic];
topic
String - The name of the topic that the message is to be published on.object_id
String - The message identifier.data
(String | JSON) - The data to be sent.Questo comando consente di ottenere una lista dello storico dei messaggi di un topic.
E' possibile configurare un offset di inizio timestamp e/o un limit e/o una query custom, in stile MongoDB, sul proprio campo data
dei messaggi.
var params = {
offset: 1460380854,
limit: -10,
query: {"data.age": {"$gte": 36}}
};
var uuid = xserv.history(topic, params);
JSONObject params = new JSONObject();
try {
params.put("offset", 1460380854);
params.put("limit", -10);
params.put("query", new JSONObject("{\"data.age\": {\"$gte\": 36}}"));
} catch (JSONException ignored) {
}
String uuid = mXserv.history(topic, params);
NSDictionary *params = @{
@"offset": [NSNumber numberWithInt:1460380854],
@"limit": [NSNumber numberWithInt:-10],
@"query": @{@"data.n": @{@"$gte": [NSNumber numberWithInt:2]}}
};
NSString *uuid = [self.xserv historyOnTopic:topic withParams:params];
topic
String - The name of the topic.params
JSON
offset
Integer [optional] - Timestamp of the message used to specify the start.limit
Integer [optional] - Value to limit the number of results. Positive is first N, negative is the last N (Default N = 1000).query
JSON [optional] - An object of data key/value pairs to filter messages on field data
(see MongoDB query find style).NOTA: Il campo query
e' applicabile solo se il vostro campo data
dei messaggi e' un JSON.
Xserv permettete di riportare il filtro esattamente a livello MongoDB, quindi sono permesse tutte le condizioni riportate nella guida
MongoDB - Query and Projection Operators.
A list of users present on a topic can be retrieved by this command.
Se si tratta di un topic privato le informazioni sono piu' dettagliate perche' hanno anche le info applicative di utenza validate al momento dell'autenticazione.
var uuid = xserv.users(topic);
String uuid = mXserv.users(topic);
NSString *uuid = [self.xserv usersOnTopic:topic];
topic
String - The name of the topic.Il comando topics consente di ottenere una lista di tutti i topic in cui c'e' almeno un client connesso.
var uuid = xserv.topics();
String uuid = mXserv.topics();
NSString *uuid = [self.xserv topics];
Funzione per ottenere l'identificativo del client connesso.
var socket_id = xserv.getSocketId();
String socket_id = mXserv.getSocketId();
NSString *socket_id = [self.xserv socketId];
Funzione disattivare l'uso del Transport Layer Security (TLS). Usare il metodo prima della connect.
xserv.disableTLS();
mXserv.disableTLS();
[self.xserv disableTLS];
Funzione per ottenere il tempo di riconnessione automatica del servizio. Il default e' 5000 millisecondi.
var milliseconds = xserv.getReconnectInterval();
Integer milliseconds = mXserv.getReconnectInterval();
long milliseconds = [self.xserv reconnectInterval];
Funzione per modificare il tempo di riconnessione automatica al servizio. Il default e' 5000 millisecondi.
xserv.setReconnectInterval(milliseconds);
mXserv.setReconnectInterval(milliseconds);
[self.xserv setReconnectInterval:milliseconds];
milliseconds
(Integer | Long) - Time interval in milliseconds.Funzione per verificare lo stato attuale della connessione.
var status = xserv.isConnected();
boolean status = mXserv.isConnected();
BOOL status = [self.xserv isConnected];
true
if the connection is established, otherwise false
.