Setting up a SwellRT Web App
In this page you can learn about:
- Configuring SwellRT JavaScript API client
- Managing server connection: sessions
- Session Lifecycle and Events
- Tips using Sessions
Add the a script tag in your web page
<script type="text/javascript" src="http://<swellrt-server-host>:<swellrt-server-port>/swellrt.js"></script>
The server runs by default at http://localhost:9898.
In order to know when SwellRT is ready to use, you can register function callbacks:
SwellRT.ready(function() {
console.log("SwellRT is ready to use");
});
SwellRT objects are always handled in the context of user sessions. To create new users please read the "Working with users" page.
It is a best practise to map SwellRT users with the app's users. However there is no restrictions to use the same SwellRT user for different app's users.
A work flow diagram of a SwellRT app follows:
A session is started with the login() method passing the user's credentials as parameters:
SwellRT.login(
// Parameters
{
id : "[email protected]",
password : s8sjf72z!3"
},
// onComplete callback
function(response) {
if (response.error) {
// ERROR
} else if (response.data) {
// OK
// response.data => user profile data
}
});
The response will return user's profile info.
Sessions are closed using the logout() method. Call it to close the current opened session.
SwellRT.logout(
function(res) {
if (res.error) {
// ERROR
} else if (res.data) {
// OK
}
});
Also it can be used to close one specific user session:
SwellRT.logout(
{
id: "[email protected]"
},
function(res) {
if (res.error) {
// ERROR
} else if (res.data) {
// OK
}
});
To start an anonymous sessions use the user SwellRT.user.ANONYMOUS and no password. The session will be only valid during the browser session.
SwellRT.login(
// Parameters
{
id : SwellRT.user.ANONYMOUS
},
function(res) {
...
});
If a previous session exists in the browser, apps can try to resume it using following method:
SwellRT.resume(
// onComplete callback
function(response) {
if (response.error) {
// ERROR
} else if (response.data) {
// OK
// response.data => user profile data
}
});
SwellRT supports different sessions in each browser tab. Sessions not explicitly closed (see logout() method) can be resumed from any new tab.
To resume a specific session, pass the user's id as first argument of the resume() method.
During a session, applications (and users) will work with collaborative objects performing live communications behind the scenes. Therefore, apps must be aware of network issues that can prevent further interaction.
The following diagram shows the session lifecycle through those network events triggered by SwellRT:
These events can be handled by applications registering callback function with the method
SwellRT.on(SwellRT.events.<global_event>, <callback_function>(data));
SwellRT.events.NETWORK_CONNECTED
Event triggered on network new connection or reconnection. The client app can resume API operations.
SwellRT.events.NETWORK_DISCONNECTED
Event triggered on a temporary or total network disconnection. The app should prevent further calls to the API until a NETWORK_CONNECTED event is received.
SwellRT.events.DATA_STATUS_CHANGED
Event triggered on data changes performed by your app. It provides three status indicators each time your app makes changes to a data model:
data.inFlightSize:
- Number of changes made in the current opened data model but not sent to the server yet.
data.uncommittedSize:
- Number of changes made in the current opened data model, already sent to the server but not commited in server storage yet.
data.unacknowledgedSize:
- Number of changes made in the current opened data model commited in the server without acknowledge.
Any local changes should trigger eventually this event with all values equals to 0. This fact will confirm that all your changes are properly stored and distributed among other participants.
Be aware of uncommited and unacknowledge changes: if a relative period of time goes by but a DATA_STATUS_CHANGED event with all values equals to zero doesn't occur, probably a communication problem exists and the app should prevent further use of the API.
SwellRT.events.FATAL_EXCEPTION
Event triggered on fatal exception in the client or server. You should stop your app. You can check data.cause for more information.
The app should start a new session (and open a model) before resuming API operations.
- Disable user interaction with collaborative objects during network disconnection periods.
- Control if DATA_STATUS_CHANGED events having all values equals to 0 are not received in an interval of 2-10 seconds. In that situation, assume you must restart the session.
- Restart a session when a fatal exception occurs or changes are not commited (see previous tip). Remeber that collaborative object instances must be open again.