Warning: You are viewing an old version (1.1) of this documentation. We recommend you view the latest version 1.2.
Realtime Client Library API

Using the Realtime library

The Realtime library when initialized attempts to establish and maintain a single connection to the Ably realtime service. This library extends the REST library to provide all REST API functionality including the authentication API. Whereas the Ably REST API is stateless, the Realtime API maintains connection and channel state.

The Ably Realtime client library is available for most popular languages and platforms with a consistent API across all platforms. You can view this documentation with your preferred language API and code examples using the language selector navigation above. If your preferred language is not listed in the language selector, we recommend you download a library in your preferred language and use this documentation as an API reference.

The Realtime library for browser JavaScript environments should be loaded from the Ably CDN as follows:

<script lang="text/javascript" src="https://cdn.ably.io/lib/ably.min-1.js"></script>

You can also obtain the library as an NPM module, or download the source directly from Github

The script and module both contain the Realtime and REST libraries as well as all their dependencies. To instantiate the Realtime library:

var realtime = new Ably.Realtime({ key: apiKey });

When including the client library from our CDN, we recommend you lock into major version 1 of the library. According to the semantic versioning scheme we adopt, you will then automatically receive minor and patch updates but you will never receive breaking changes. For example, if you lock into major version 1 of the library by including https://cdn.ably.io/lib/ably.min-1.js, you will receive all minor updates and patch fixes automatically (i.e 1.*.*). If you want to lock into minor version 1.0 and receive all patch fixes automatically (i.e. 1.0.*), then use https://cdn.ably.io/lib/ably.min-1.0.js. Additionally, the .min suffix can be dropped if you want the non-minified version for debugging.

View a complete list of the JavaScript library releases

The Realtime library for Node.js is suitable for clients and servers and is hosted on Github and is obtainable as an NPM module directly from npm. Install with:

npm install ably

The Ably Node.js module contains both the REST and Realtime libraries; each is exported separately by the module. To instantiate the Realtime library:

var Ably = require('ably');
var realtime = new Ably.Realtime({ key: apiKey });

The Realtime library for Ruby hosted on Github and is published as a RubyGem and can be installed as follows:

gem install ably

If using bundler, simply add the following to your Gemfile and run bundle install:

gem 'ably'

The Ably Ruby gem contains both the REST and Realtime libraries; each is namespaced separately by the gem. The Realtime library must be run within an EventMachine reactor which provides an asynchronous evented framework for the library to run within. To instantiate the Realtime library:

EventMachine.run do
  ably = Ably::Realtime.new(key: api_key)
end

If you are using Ably in your Rails or Sinatra apps, you probably want to be using the Ably REST library that offers a synchronous API and has no dependency on EventMachine.

The Realtime library for Java and Android is hosted on Github and can be used by adding one line to build.gradle dependencies section.

For Java applications:

compile 'io.ably:ably-java:1.1.0'

For Android apps:

compile 'io.ably:ably-android:1.1.0'

In the above example a specific version of the library is referenced, however we recommend you check which is the latest stable version and always use that. Follow links to get the latest stable release for Java and Android.

Ensure the library is included in your classpath as follows:

import io.ably.lib.types.*;
import io.ably.lib.realtime.*;
ClientOptions options = new ClientOptions(apiKey);
AblyRealtime realtime = new AblyRealtime(options);

The Realtime library for .NET is available as a Nuget Package. Open the nuget console in visual studio and type.

PM> Install-Package ably.io

Alternatively, search for the ‘ably.io’ package through the Nuget UI

using IO.Ably;

ClientOptions clientOptions = new ClientOptions("<API Key>");
AblyRealtime realtime = new AblyRealtime(clientOptions);

The Ably library is hosted on Github and is available as a CocoaPod. Add this line to your application’s Podfile:

pod 'Ably'

And install with pod install. Then in your files:

#import "Ably/Ably.h"

ARTRealtime realtime = [[ARTRealtime alloc] initWithKey:apiKey];
import Ably

let realtime = ARTRealtime(key: apiKey)

Note: Since version 1.0.8, the iOS client libraries are thread-safe. Check the README for details.

View our client library SDKs feature support matrix to see the list of all the available features.

The supported client options are described in the API reference.

Tutorials

If you would like to see examples of using the Ably Realtime client library, then we recommend you take a look at our Realtime tutorials.

API Reference

View the Constructor API Reference.


Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.