Getting Started

Before hacking away, you'll need a home for your data. The first step in using Convergence is to log in to the web-based Convergence Administration Console and either create a domain or verify the information for an existing domain you wish to use. Make sure that this domain has at least one user, as you will need that user's credentials to connect to the domain.


Domains provide an organizational structure for your applications. Convergence users (you, not your application's end user) can create and use multiple domains. Each domain has its own set of users, data, security rules, etc. In essence, each domain is its own entire collaborative ecosystem. Having multiple domains is convenient if you have multiple applications, or if you have a production application and would like to have a sandbox to play in without affecting your production users.

JavaScript / HTML Setup

Convergence requires a few things to get going. First you need the convergence client. Since Convergence uses RxJs, you also need to include the RxJs client as well. The quickest way to get started is to add the following HTML to the head tag of your page:

    <script src=""></script>

We plan on offering several bundling and script loading options in the future, such as bundling RxJS and providing AMD, CommonJS, and ES6 modules. For now, though, this is the simplest way to get started. Ensure that the RxJS script tag is added BEFORE the Convergence client.


The first step after setup is to connect to your domain. The simplest way to connect is using a username and password for a domain user. The connect method returns a promise that will either complete with the connected domain, or will be rejected with an error detailing why the connection was not successful.

var domainUrl = "<username>/<domainId>";
Convergence.connect(domainUrl, "Bruce Wayne", "1AmBatman!").then((domain) => {
  // Connection success! See below for the API methods available on this domain
}).catch((err) => {


The domain is the main entry point into the convergence API. The features it provides are grouped into high level services. Getting to know these services is the next step in learning how to use Convergence to build a collaborative app.

  • Identity Service: Provides services to obtain information on the identity of users in the system.
  • Presence Service: Provides services to see who is available in the system and publish shared state.
  • Model Service: Provides services to store, retrieve, and edit shared data models.
  • Activity Service: Provides services to more gradually communicate who is doing what in an application.
  • Chat Service: Provides services for users to send messages to each other to coordinate actions and share information.

Each service is discussed in detail in subsequent chapters. Examples of how to obtain the services are below:

 const identityService = domain.identity();
 const presenceService = domain.presence();
 const modelService = domain.models();
 const activtiyService = domain.activities();
 const chatService =;

Clean Up

TODO add bit about what happens when you don't dispose and e.g. open up another domain

When the client no longer needs to use the domain, such as when they log out, the client should call the ConvergenceDomain.dispose() method. This method will log the user out, disconnect the client, and release the resources associated with the domain. Following this call, any further calls to the domain methods will likely result in excpetions and/or rejected promises.

// Logout and disconnect

results matching ""

    No results matching ""