Getting Started

Overview

Realtime Engine provides efficient, reliable, secured and easy-to-use bidirectional communication service to assist you to build user-friendly realtime application of Web and mobile quickly.

Suitable application scenarios:

  • Online cooperation, for example, sync up a user’s operations to another user’s screen in real time
  • MMOG (Massively Multiplayer Online Game)
  • Realtime data monitoring, such as stock price volatility and sensor monitoring data
  • Realtime messages, and text, image, audio, video chats, etc.
  • …

If developers implement such services themselves, they usually need to consider the following problems:

  • High concurrency processing on servers
  • Horizontal scaling on servers
  • Selection and customization of communication protocols, as well as reliability and panetrability of complicated network environment
  • Cross platforms, compatibility of Android, iOS and Windows Phone as well as Web browser
  • …

The use of Realtime Engine of TuiSongBao can help you out of these troubles and specialize in the development of core functions:

Contrast with Push Service

Push Service only supports clients of Android, iOS and Windows Phone. The communication is one-way and can only be pushed from the server to the client, but the push can still be received even though an application is not launched. It is suitable for pushing offline notifications, waking up applicaitons and enhancing user engagement.

Realtime Engine supports both mainstream mobile clients and Web. The communication to clients is bidirenctional, but resident background service is not provided on mobile clients. Messages cannot be received if an application has completely exited. It is suitable for user realtime online interaction

Push Service can be an effective supplement of Realtime Engine. For example, in the chat scenario, if the counterpart is not online, you can push notifications to him/her.

Working Principle

For the details on the interaction of your servers and clients with Realtime Engine, see below:

Endpoint Interaction Diagram

On the client, the WebSocket persistent connection is used to communicate with Realtime Engine, while HTTP protocol used on the server. If messages need to be notified to the server in real time, WebHook can be used (see below):

The reason why the communication between application server and Realtime Engine server does not use WebSocket is because:

  • It is not convenient for certain server programming languages to use persistent connection for communications. For instance, directly using the proven HTTP for PHP can reduce complexity.
  • Using HTTP can make it easier to handle errors and implement load balancing.

Application Pattern

Based on the same realtime channel, Realtime Engine provides different applicaiton patterns to meet various demands of applilcaitons, including the two kinds below:

  • Pub/Sub: Please refer to Definition of Wikipedia. It is highly flexible to support various realtime applications with unique requirements.
  • Chat: The encapsulation of the common Chat function, including single chat, group chat, friendship, offline messages, multimedia messages, and so forth makes it easier and quicker to add the IM function for your appication.

Main Components and Concepts

Engine

App ID needs to be passed in to use the entry point to client SDK of Realtime Engine.

For more details, please refer to the corresponding SDK documentation.

Connection

Connection refers to the communication connection from a client to Realtime Engine. Generally, WebSocket is used, and will be replaced with XHR Polling if not available on Web.

For more details, see Connection.

For more details, see Pub/Sub 。

For more details, see Chat 。

Open API

Realtime Engine provides easy-to-use RESTful API for application servers to call.

For more details, see Realtime Engine Open API 。

WebHook

The WebHook mechanism means when a specific event happens, the server of Realtime Engine will notify the applicaiton server in a way of HTTP POST to make it easy for special handlings.

For more detials, see WebHook 。

Examples

The following are the simple examples of JavaScript client and Node.js server when using the Pub/Sub mode. For more details, please refer to the corresponding SDK and API documentation.

JavaScript Client：

// Instantialize an Engine instance
var engine = new Engine('YOUR_APP_ID');

// Subscribe comments Channel
var coolChannel = engine.channels.subscribe('comments');

// Listen for the comment-added event on comments Channel 
coolChannel.bind('comment-added', function (data) {
    // Now the event is triggered and handled accordingly
    alert(data);
});

Node.js Server：

var request = require('superagent');

// Call Open API to triger the comment-added event on comments Channel and pass data, and then the callback for listening for the event that is set in the above example will be executed.
request
.post('https://api.tuisongbao.com/v2/open/engine/events')
.auth('53c73242547c8736024678e7', 'ae9578feebf46861d5a0bd9a')
.send({
    name: 'comment-added',
    data: {
        postId: 123,
        commentId: 456
    },
    channels: ["comments"]
})
.end();

Online Demo

Notes

As for the Pub/Sub mode, Realtime Engine only provides the transmission channel function, but will not persist Event that is transmitted. We will do our best to deliver Event, but it will be discarded when the client is offline due to network problems, that is to say the offline messages are not available. If needed, developers are supposed to handle it through their own servers.

As for the Chat mode, apart from providing efficient data transmission channel, Realtime Engine will meanwhile persist the chat messages that are transmitted. When the client comes online, we will provide notification and message delivery services.

Next Step

Before integration, please sign up on our website and create an application with the service type of Realtime Engine, and then in the application, go to [Settings] -> [Secret] to get your App ID as well as Secret.

To use Realtime Engine, integrate the following two parts respectively:

  • Client: From the left navigation, select the language and platform to be used, and follow the guide to integrate. If we haven’t yet provided the client SDK for the language or platform you are using, please contact us.
  • Server: Please refer to Realtime Engine Open API.
  Back To Top