Ably is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably’s platform to offload the growing complexity of business-critical realtime data synchronization at global scale. For more information, see the Ably documentation.
This is a JavaScript client library for Ably Realtime.
This library currently targets the Ably client library features spec Version 1.2. You can jump to the 'Known Limitations' section to see the features this client library does not yet support or view our client library SDKs feature support matrix to see the list of all the available features.
This SDK supports the following platforms:
Browsers: All major desktop and mobile browsers, including (but not limited to) Chrome, Firefox, IE (only version 9 or newer), Safari on iOS and macOS, Opera, and Android browsers.
Webpack: see using Webpack in browsers, or our guide for serverside Webpack
Node.js: version 8.17 or newer. (1.1.x versions work on Node.js 4.5 or newer). We do not currently provide an ESM bundle, please contact us if you would would like to use ably-js in a NodeJS ESM project.
React Native: We aim to support all platforms supported by React Native. If you find any issues please raise an issue or contact us.
NativeScript: see ably-js-nativescript
TypeScript: see below
WebWorkers: We build a separate bundle which supports running in a Web Worker context. You can import it like this:
import Ably from 'ably/build/ably-webworker.min';We regression-test the library against a selection of those (which will change over time, but usually consists of the versions that are supported upstream, plus old versions of IE).
However, we aim to be compatible with a much wider set of platforms and browsers than we can possibly test on. That means we'll happily support (and investigate reported problems with) any reasonably-widely-used browser. So if you find any compatibility issues, please do raise an issue in this repository or contact Ably customer support for advice.
Ably-js has fallback mechanisms in order to be able to support older browsers; specifically it supports comet-based connections for browsers that do not support websockets, and this includes JSONP for browsers that do not support cross-origin XHR. Each of these fallback transport mechanisms is supported and tested on all the browsers we test against, even when those browsers do not themselves require those fallbacks. These mean that the library should be compatible with nearly any browser on most platforms. Known browser incompatibilities will be documented as an issue in this repository using the "compatibility" label.
For complete API documentation, see the Ably documentation.
npm install ably --save
and require as:
var Ably = require('ably');For the version of the library where async methods return promises, use var Ably = require('ably/promises'); instead. For the explicitly-callback-based variant use require('ably/callbacks')– see Async API style.
For usage, jump to Using the Realtime API or Using the REST API.
If you are using a version older than 1.2.5 you will need to add 'ably' to externals in your webpack config to exclude it from webpack processing, and require and use it in as a external module using require('ably') as above.
Include the Ably library in your HTML:
<script src="https://cdn.ably.com/lib/ably.min-1.js"></script>The Ably client library follows Semantic Versioning. To lock into a major or minor version of the client library, you can specify a specific version number such as https://cdn.ably.com/lib/ably.min-1.js for all v1._ versions, or https://cdn.ably.com/lib/ably.min-1.0.js for all v1.0._ versions, or you can lock into a single release with https://cdn.ably.com/lib/ably.min-1.0.9.js. Note you can load the non-minified version by omitting min- from the URL such as https://cdn.ably.com/lib/ably-1.0.js. See https://github.com/ably/ably-js/tags for a list of tagged releases.
For usage, jump to Using the Realtime API or Using the REST API.
(This applies to using webpack to compile for a browser; for Node.js, see Serverside usage with webpack)
WebPack will search your node_modules folder by default, so if you include ably in your package.json file, when running Webpack the following will allow you to require('ably') (or if using typescript or ES6 modules, import * as Ably from 'ably';). If your webpack target is set to 'browser', this will automatically use the browser commonjs distribution.
If that doesn't work for some reason (e.g. you are using a custom webpack target), you can reference the ably-commonjs.js static file directly: require('ably/browser/static/ably-commonjs.js'); (or import * as Ably from 'ably/browser/static/ably-commonjs.js' for typescript / ES6 modules).
The TypeScript typings are included in the package and so all you have to do is:
import * as Ably from 'ably';
let options: Ably.Types.ClientOptions = { key: 'foo' };
let client = new Ably.Realtime(options); /* inferred type Ably.Realtime */
let channel = client.channels.get('feed'); /* inferred type Ably.Types.RealtimeChannel */For the version of the library where async methods return promises, use import * as Ably from 'ably/promises'; instead. For the explicitly-callback-based variant use import * as Ably from 'ably/callbacks' – see Async API style.
Intellisense in IDEs with TypeScript support is supported:
If you need to explicitly import the type definitions, see ably.d.ts (or promises.d.ts if you're requiring the library as ably/promises).
This library exposes two API variants. Firstly, the original (and presently the default) callback-based API, which follows the usual Node.js error-first callback style. Second, a promises-based API. With the promises variant, you can still pass a callback to methods and the callback will work as expected, but if you do not pass a callback, the method will return a promise. The API in use can be selected explicitly by requiring that specific variant when requiring/importing the library (or in the case of the browser version, when instantiating it). The usage instructions below make reference to both variants.
For this library version, and for all future 1.x versions, the callback-based API will be the default. This means that the promises-based variant will need to be explicitly selected, to avoid breaking backwards compatibility. A move to the promises-based variant as the default is likely at the next major release (i.e. 2.x onwards).
For usage, jump to Using the async API style.
See the ably-js-nativescript repo for NativeScript usage details.
This readme gives some basic examples; for our full API documentation, please go to https://www.ably.com/docs .
All examples assume a client has been created as follows:
// basic auth with an API key
var client = new Ably.Realtime(key: string);
// using a Client Options object, see https://www.ably.com/docs/rest/usage#client-options
// which must contain at least one auth option, i.e. at least
// one of: key, token, tokenDetails, authUrl, or authCallback
var client = new Ably.Realtime(options: ClientOptions);
// For a version of the library where async methods return promises if
// you don't pass a callback:
var client = new Ably.Realtime.Promise(options: string | ClientOptions);
// For the explicitly-callback-based variant (see 'Async API style' below):
var client = new Ably.Rest.Callbacks(options: string | ClientOptions);Successful connection:
client.connection.on('connected', function() {
# successful connection
});Failed connection:
client.connection.on('failed', function() {
# failed connection
});Given:
var channel = client.channels.get('test');Subscribe to all events:
channel.subscribe(function (message) {
message.name; // 'greeting'
message.data; // 'Hello World!'
});Only certain events:
channel.subscribe('myEvent', function (message) {
message.name; // 'myEvent'
message.data; // 'myData'
});Subscribing to a channel in delta mode enables delta compression. This is a way for a client to subscribe to a channel so that message payloads sent contain only the difference (ie the delta) between the present message and the previous message on the channel.
Configuring a channel for deltas is detailed in the @ably-forks/vcdiff-decoder documentation.
Beyond specifying channel options, the rest is transparent and requires no further changes to your application. The message.data instances that are delivered to your listening function continue to contain the values that were originally published.
If you would like to inspect the Message instances in order to identify whether the data they present was rendered from a delta message from Ably then you can see if extras.delta.format equals 'vcdiff'.
// Publish a single message with name and data
channel.publish('greeting', 'Hello World!');
// Optionally, you can use a callback to be notified of success or failure
channel.publish('greeting', 'Hello World!', function(err) {
if(err) {
console.log('publish failed with error ' + err);
} else {
console.log('publish succeeded');
}
})
// Publish several messages at once
channel.publish([{name: 'greeting', data: 'Hello World!'}, ...], callback);channel.history(function(err, messagesPage) {
messagesPage // PaginatedResult
messagesPage.items // array of Message
messagesPage.items[0].data // payload for first message
messagesPage.items.length // number of messages in the current page of history
messagesPage.hasNext() // true if there are further pages
messagesPage.isLast() // true if this page is the last page
messagesPage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult
});
// Can optionally take an options param, see https://www.ably.com/docs/rest-api/#message-history
channel.history({start: ..., end: ..., limit: ..., direction: ...}, function(err, messagesPage) { ...});Getting presence:
channel.presence.get(function (err, presenceSet) {
presenceSet; // array of PresenceMessages
});Note that presence#get on a realtime channel does not return a PaginatedResult, as the library maintains a local copy of the presence set.
Entering (and leaving) the presence set:
channel.presence.enter('my status', function (err) {
// now I am entered
});
channel.presence.update('new status', function (err) {
// my presence data is updated
});
channel.presence.leave(function (err) {
// I've left the presence set
});If you are using a client which is allowed to use any clientId -- that is, if you didn't specify a clientId when initializing the client, and are using basic auth or a token witha wildcard clientId (see https://www.ably.com/docs/general/authentication for more information), you can use
channel.presence.enterClient('myClientId', 'status', function(err) { ... });
// and similiarly, updateClient and leaveClientchannel.presence.history(function(err, messagesPage) { // PaginatedResult
messagesPage.items // array of PresenceMessage
messagesPage.items[0].data // payload for first message
messagesPage.items.length // number of messages in the current page of history
messagesPage.hasNext() // true if there are further pages
messagesPage.isLast() // true if this page is the last page
messagesPage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult
});
// Can optionally take an options param, see https://www.ably.com/docs/rest-api/#message-history
channel.presence.history({start: ..., end: ..., limit: ..., direction: ...}, function(err, messagesPage) { ...});When a 128 bit or 256 bit key is provided to the library, the data attributes of all messages are encrypted and decrypted automatically using that key. The secret key is never transmitted to Ably. See https://www.ably.com/docs/realtime/encryption
// Generate a random 256-bit key for demonstration purposes (in
// practice you need to create one and distribute it to clients yourselves)
Ably.Realtime.Platform.Crypto.generateRandomKey(function (err, key) {
var channel = client.channels.get('channelName', { cipher: { key: key } });
channel.subscribe(function (message) {
message.name; // 'name is not encrypted'
message.data; // 'sensitive data is encrypted'
});
channel.publish('name is not encrypted', 'sensitive data is encrypted');
});You can also change the key on an existing channel using setOptions (which takes a callback which is called after the new encryption settings have taken effect):
channel.setOptions({cipher: {key: <key>}}, function() {
// New encryption settings are in effect
})Message Interactions allow you to interact with messages previously sent to a channel. Once a channel is enabled with Message Interactions, messages received by that channel will contain a unique timeSerial that can be referenced by later messages.
Example emoji reaction to a message:
function sendReaction(emoji) {
channel.publish('event_name', { body: emoji, extras: { ref: { type: "com.ably.reaction", timeserial: "1656424960320-1" } } })
}See https://www.ably.com/docs/realtime/messages#message-interactions for more detail.
This readme gives some basic examples. For our full API documentation, please go to https://www.ably.com/docs .
All examples assume a client and/or channel has been created as follows:
// basic auth with an API key
var client = new Ably.Rest(key: string);
// using a Client Options object, see https://www.ably.com/docs/realtime/usage#client-options
// which must contain at least one auth option, i.e. at least
// one of: key, token, tokenDetails, authUrl, or authCallback
var client = new Ably.Rest(options: ClientOptions);
// For a version of the library where async methods return promises if
// you don't pass a callback:
var client = new Ably.Rest.Promise(options: string | ClientOptions);
// For the explicitly-callback-based variant (see 'Async API style' above):
var client = new Ably.Rest.Callbacks(options: string | ClientOptions);Given:
var channel = client.channels.get('test');// Publish a single message with name and data
channel.publish('greeting', 'Hello World!');
// Optionally, you can use a callback to be notified of success or failure
channel.publish('greeting', 'Hello World!', function(err) {
if(err) {
console.log('publish failed with error ' + err);
} else {
console.log('publish succeeded');
}
})
// Publish several messages at once
channel.publish([{name: 'greeting', data: 'Hello World!'}, ...], callback);channel.history(function(err, messagesPage) {
messagesPage // PaginatedResult
messagesPage.items // array of Message
messagesPage.items[0].data // payload for first message
messagesPage.items.length // number of messages in the current page of history
messagesPage.hasNext() // true if there are further pages
messagesPage.isLast() // true if this page is the last page
messagesPage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult
});
// Can optionally take an options param, see https://www.ably.com/docs/rest-api/#message-history
channel.history({start: ..., end: ..., limit: ..., direction: ...}, function(err, messagesPage) { ...});channel.presence.get(function(err, presencePage) { // PaginatedResult
presencePage.items // array of PresenceMessage
presencePage.items[0].data // payload for first message
presencePage.items.length // number of messages in the current page of members
presencePage.hasNext() // true if there are further pages
presencePage.isLast() // true if this page is the last page
presencePage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult
});channel.presence.history(function(err, messagesPage) { // PaginatedResult
messagesPage.items // array of PresenceMessage
messagesPage.items[0].data // payload for first message
messagesPage.items.length // number of messages in the current page of history
messagesPage.hasNext() // true if there are further pages
messagesPage.isLast() // true if this page is the last page
messagesPage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult
});
// Can optionally take an options param, see https://www.ably.com/docs/rest-api/#message-history
channel.history({start: ..., end: ..., limit: ..., direction: ...}, function(err, messagesPage) { ...});channel.status(function(err, channelDetails) {
channelDetails.channelId // The name of the channel
channelDetails.status.isActive // A boolean indicating whether the channel is active
channelDetails.status.occupancy // Contains metadata relating to the occupants of the channel
});See https://www.ably.com/docs/general/authentication for an explanation of Ably's authentication mechanism.
Requesting a token:
client.auth.requestToken(function(err, tokenDetails) {
// tokenDetails is instance of TokenDetails
// see https://www.ably.com/docs/rest/authentication/#token-details for its properties
// Now we have the token, we can send it to someone who can instantiate a client with it:
var clientUsingToken = new Ably.Realtime(tokenDetails.token);
});
// requestToken can take two optional params
// tokenParams: https://www.ably.com/docs/rest/authentication/#token-params
// authOptions: https://www.ably.com/docs/rest/authentication/#auth-options
client.auth.requestToken(tokenParams, authOptions, function(err, tokenDetails) { ... });Creating a token request (for example, on a server in response to a
request by a client using the authCallback or authUrl mechanisms):
client.auth.createTokenRequest(function(err, tokenRequest) {
// now send the tokenRequest back to the client, which will
// use it to request a token and connect to Ably
});
// createTokenRequest can take two optional params
// tokenParams: https://www.ably.com/docs/rest/authentication/#token-params
// authOptions: https://www.ably.com/docs/rest/authentication/#auth-options
client.auth.createTokenRequest(tokenParams, authOptions, function(err, tokenRequest) { ... });client.stats(function(err, statsPage) { // statsPage as PaginatedResult
statsPage.items // array of Stats
statsPage.items[0].inbound.rest.messages.count; // total messages published over REST
statsPage.items.length; // number of stats in the current page of history
statsPage.hasNext() // true if there are further pages
statsPage.isLast() // true if this page is the last page
statsPage.next(function(nextPage) { ... }); // retrieves the next page as PaginatedResult
});client.time(function(err, time) { ... }); // time is in ms since epochimport * as Ably from 'ably/promises';
const client = new Ably.Realtime.Promise(options);
const ablyRealtimePromiseExample = async () => {
const channel = client.channels.get('myChannel');
// Attaching to a channel
await channel.attach();
// Getting presence on a channel
const presenceMessage = await channel.presence.get();
console.log(presenceMessage);
// Updating presence on a client
await channel.presence.enter();
await channel.presence.update('new status');
await channel.presence.leave();
// Publishing a message
await channel.publish('greeting', 'Hello, World!');
// Querying history
const history = await channel.history({ limit: 25 });
console.log(history);
client.close();
};
ablyRealtimePromiseExample();import * as Ably from 'ably/promises';
const client = new Ably.Rest.Promise(options);
const ablyRestPromiseExample = async () => {
const channel = client.channels.get('myChannel');
// Publishing a message
await channel.publish('greeting', 'Hello, World!');
// Getting presence on a channel
const presenceMessage = await channel.presence.get();
console.log(presenceMessage);
// Querying history
const history = await channel.history({ limit: 25 });
console.log(await history.current());
// Getting the status of a channel
const channelDetails = await channel.status();
console.log(channelDetails);
// Requesting a token
const token = await client.auth.requestToken(tokenParams);
// Creating a token request
const tokenRequest = await client.auth.createTokenRequest();
// Fetching your application's stats
const stats = await client.stats();
console.log(stats);
// Fetching the Ably service time
const time = await client.time();
console.log(`Ably service time: ${time}`);
client.close();
};
ablyRestPromiseExample();From version 1.2 this client library supports subscription to a stream of Vcdiff formatted delta messages from the Ably service. For certain applications this can bring significant data efficiency savings. This is an optional feature so our
See the @ably-forks/vcdiff-decoder documentation for setup and usage examples.
Please visit http://support.ably.com/ for access to our knowledgebase and to ask for any assistance.
You can also view the community reported Github issues.
To see what has changed in recent versions, see the CHANGELOG.
This library currently does not support being the target of a push notification (i.e. web push).
For guidance on how to contribute to this project, see the CONTRIBUTING.md.
Automated browser testing supported by
