Introduction


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'.


Topic concept


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.


Tipologie di topic


Esistono al momento 3 tipi di topic:

  • Public topic permette il subscribe a tutti quelli che ne conoscono il nome.
  • Private topic devono avere come prefisso nel nome @ e il subscribe su questo topic necessita di un webhook di autenticazione.
  • User topic nella forma !<socket_id>, ogni client connesso ad Xserv ha il suo e serve ad inviare un messaggio diretto one-to-one.

Naming convensions


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.


Project setup


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'

Connector


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.


Creazione del connettore


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.

Connessione a Xserv


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.


Disconnessione da Xserv


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];

Event listeners


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.


Connection events


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 {
    ...
}

Messages


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 {
    ...
}
  • json 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.

Operation responses


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 {
    ...
}
  • json 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.

Subscribe


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.
  • Return String
    • The universally unique identifier of the operation.

Subscribe private


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).
  • Return String
    • The universally unique identifier of the operation.

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.


Unsubscribe


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.
  • Return String
    • The universally unique identifier of the operation.

Publish


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.
  • Return String
    • The universally unique identifier of the operation.

Update


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.
  • Return String
    • The universally unique identifier of the operation.

History


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).
  • Return String
    • The universally unique identifier of the operation.

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.


Users


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.
  • Return String
    • The universally unique identifier of the operation.

TOPICS


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];
  • Return String
    • The universally unique identifier of the operation.

Altre funzioni


Socket Id

Funzione per ottenere l'identificativo del client connesso.

var socket_id = xserv.getSocketId();
String socket_id = mXserv.getSocketId();
NSString *socket_id = [self.xserv socketId];
  • Return String
    • The session identifier for the specific client connection to Xserv.


Disable TLS

Funzione disattivare l'uso del Transport Layer Security (TLS). Usare il metodo prima della connect.

xserv.disableTLS();
mXserv.disableTLS();
[self.xserv disableTLS];


Reconnect Interval

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];
  • Return (Integer | Long)
    • Time interval in milliseconds.

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.


Connected check

Funzione per verificare lo stato attuale della connessione.

var status = xserv.isConnected();
boolean status = mXserv.isConnected();
BOOL status = [self.xserv isConnected];
  • Return Boolean
    • true if the connection is established, otherwise false.