Warning: You are viewing an old version (0.8) 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. The 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, please download the library in your preferred language and use that as a reference.

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

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

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 0 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 0 of the library by including https://cdn.ably.io/lib/ably.min-0.js, you will receive all minor updates and patch fixes automatically (i.e 0.*.*). If you want to lock into minor version 0.8 and receive all patch fixes automatically (i.e. 0.8.*), then use https://cdn.ably.io/lib/ably.min-0.8.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. To instantiate the Realtime library:

ably = Ably::Realtime.new(key: api_key)

The Realtime library for Java and Android is hosted on Github and is downloadable as a JAR from https://github.com/ably/ably-java/releases.

Ensure the JAR 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 'AblyRealtime'

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: The 0.8 iOS client libraries are not thread-safe. If you can’t upgrade to 1.0, we recommend that you ensure that all operations on a ARTRest or ARTRealtime object happen in the same Grand Central Dispatch serial queue. Also, it’s undefined from which queue or thread will callback blocks provided to the Ably library be called. This queue may be the same queue you use to call Ably, so if you’re calling another Ably operation from your callback, you should only dispatch a new task for it if you’re not already in Ably’s queue. For example:

@implementation YourClass {
    dispatch_queue_t _ablyQueue;
    ARTRealtime *ably;
}

- (void)initializeAbly {
    _ablyQueue = dispatch_queue_create("com.example.ably", NULL);
    [self doAblyOperation:^{
        _ably = [ARTRealtime initWithOptions:[self ablyOptions]];
    }];
}

- (void)subscribeToAbly {
    [self doAblyOperation:^{
        [[_ably.channels get:@"foo"] subscribe:^(ARTMessage *message) {
            // Answer back.
            [self doAblyOperation:^{
                [[_ably.channels get:@"foo"] publish:@"reply" data:@"Hi back!"];
            }];
        }];
    }];
}

- (void)doAblyOperation:(dispatch_block_t)block {
    // Make sure we're not already in the Ably queue! This can happen if Ably
    // calls our callback from the same task we dispatch.
    if (dispatch_get_current_queue() == _ablyQueue) {
        block();
    } else {
        dispatch_sync(_ablyQueue, block);
    }
}
class YourClass {
    var ablyQueue: DispatchQueue!
    var ably: ARTRealtime!

    func initializeAbly() {
        self.ablyQueue = DispatchQueue(label: "com.example.ably")
        self.doAblyOperation {
            self.ably = ARTRealtime(options: self.ablyOptions)
        }
    }

    func subscribeToAbly() {
        self.doAblyOperation {
            self.ably.channels.get("foo").subscribe { message in
                // Answer back.
                self.doAblyOperation {
                    self.ably.channels.get("foo").publish("reply", data:"Hi back!")
                }
            }
        }
    }

    func doAblyOperation(_ operation: () -> Void) {
        // Make sure we're not already in the Ably queue! This can happen if Ably
        // calls our callback from the same task we dispatch.
        if (String(validatingUTF8: __dispatch_queue_get_label(nil)) == "com.example.ably") {
            operation()
        } else {
            self.ablyQueue.sync(execute: operation)
        }
    }
}

The library is thread-safe on the 1.0 branch, starting from version 1.0.8.

The supported client options are described in the API reference.

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.