Version 0.8.2
![Build Status](https://travis-ci.org/ably/ably-js.png)
This repo contains the ably javascript client libraries, both for the browser and nodejs.
For complete API documentation, see the ably documentation.
For node.js
Installation
From npm
npm install ably-js
From a git url
npm install <git url>
From a local clone of this repo
cd </path/to/this/repo>
npm install
Usage
With Node.js
For the realtime library:
var realtime = require('ably-js').Realtime;
For the rest-only library:
var rest = require('ably-js').Rest;
With the Browser library
Include the Ably library in your HTML:
<script src="https://cdn.ably.io/lib/ably.min.js"></script>
The Ably client library follows Semantic Versioning. To lock into a major or minor verison of the client library, you can specify a specific version number such as http://cdn.ably.io/lib/ably.min-0.8.2.js or http://cdn.ably.io/lib/ably-0.8.2.js for the non-minified version. See https://github.com/ably/ably-js/tags for a list of tagged releases.
For the real-time library:
var realtime = Ably.Realtime;
For the rest-only library:
var rest = Ably.Rest;
Using the Realtime API
Introduction
All examples assume a client has been created as follows:
var client = new Ably.Realtime(<key string>)
// using token auth
var client = new Ably.Realtime(<token string>)
Connection
Successful connection:
client.connection.on('connected', function() {
# successful connection
});
Failed connection:
client.connection.on('failed', function() {
# failed connection
});
Subscribing to a channel
Given:
var channel = client.channels.get('test');
Subscribe to all events:
channel.subscribe(function(message) {
message.name
message.data
});
Only certain events:
channel.subscribe('myEvent', function(message) {
message.name
message.data
});
Publishing to a channel
channel.publish('greeting', 'Hello World!')
Querying the History
channel.history(function(messagesPage) {
messagesPage
messagesPage.items
messagesPage.items[0].data
messagesPage.items.length
messagesPage.next(function(nextPage) { ... });
messagesPage.next == undefined
});
Presence on a channel
channel.presence.get(function(presencePage) {
presencePage.items
presencePage.items[0].data
presencePage.items.length
presencePage.next(function(nextPage) { ... });
presencePage.next == undefined
});
channel.presence.enter('my status', function() {
});
Querying the Presence History
channel.presence.history(function(messagesPage) {
messagesPage.items
messagesPage.items[0].data
messagesPage.items.length
messagesPage.next(function(nextPage) { ... });
messagesPage.next == undefined
});
Using the REST API
Introduction
All examples assume a client and/or channel has been created as follows:
var client = new Ably.Realtime(<key string>)
// using token auth
var client = new Ably.Realtime(<token string>)
Given:
var channel = client.channels.get('test');
Publishing to a channel
channel.publish('greeting', 'Hello World!')
Querying the History
channel.history(function(messagesPage) {
messagesPage
messagesPage.items
messagesPage.items[0].data
messagesPage.items.length
messagesPage.next(function(nextPage) { ... });
messagesPage.next == undefined
});
Presence on a channel
channel.presence.get(function(presencePage) {
presencePage.items
presencePage.items[0].data
presencePage.items.length
presencePage.next(function(nextPage) { ... });
presencePage.next == undefined
});
Querying the Presence History
channel.presence.history(function(messagesPage) {
messagesPage.items
messagesPage.items[0].data
messagesPage.items.length
messagesPage.next(function(nextPage) { ... });
messagesPage.next == undefined
});
Generate Token and Token Request
client.auth.requestToken(function(err, tokenDetails) {
token_details.token
});
var clientUsingToken = new Ably.Rest(token_details.token);
client.auth.createTokenRequest(function(err, tokenRequest) {
tokenRequest.keyName
tokenRequest.clientId
tokenRequest.ttl
tokenRequest.timestamp
tokenRequest.capability
tokenRequest.nonce
tokenRequest.mac
Fetching your application's stats
client.stats(function(statsPage) {
statsPage.items
statsPage.next(function(nextPage) { ... });
});
Fetching the Ably service time
client.time(function(time) { ... });
Test suite
To run both the NodeUnit & Karma Browser tests, simply run the following command:
grunt test
NodeUnit Tests
Run the NodeUnit test suite
grunt test:nodeunit
Or run just one or more test files
grunt test:nodeunit --test spec/realtime/auth.test.js
Browser Tests
Browser tests are run using Karma test runner.
To build & run the tests in a single step
grunt test:karma
Debugging the tests in your browser with NodeUnit test runner
Simply open spec/nodeunit.html in your browser to run the test suite with a nice GUI.
Note: If any files have been added or remove, running the task grunt requirejs
will ensure all the necessary RequireJS dependencies are loaded into the browser by updating spec/support/browser_file_list.js
Debugging the tests in a remote browser with NodeUnit test runner
Run the following command to start a local Nodeunit test runner web server
grunt test:webserver
Open your browser to http://localhost:3000. If you are usig a remote browser, refer to https://docs.saucelabs.com/reference/sauce-connect/ for instructions on setting up a local tunnel to your Nodeunit runner web server.
Debugging the tests in your browser with Karma
If you would like to run the tests through Karma, then:
Start a Karma server
karma server
You can optionally connect your browser to the server, visit http://localhost:9876/
Click on the Debug button in the top right, and open your browser's debugging console.
Then run the tests against the Karma server. The test:karma:run
command will concatenate the Ably files beforehand so any changes made in the source will be reflected in the test run.
grunt test:karma:run
Testing environment variables
All tests are run against the sandbox environment by default. However, the following environment variables can be set before running the Karma server to change the environment the tests are run against.
ABLY_ENV
- defaults to sandbox, however this can be set to another known environment such as 'staging'ABLY_REALTIME_HOST
- explicitly tell the client library to use an alternate host for real-time websocket communication.ABLY_REST_HOST
- explicitly tell the client library to use an alternate host for REST communication.ABLY_PORT
- non-TLS port to use for the tests, defaults to 80ABLY_TLS_PORT
- TLS port to use for the tests, defaults to 443
Support and feedback
Please visit https://support.ably.io/ for access to our knowledgebase and to ask for any assistance.
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Ensure you have added suitable tests and the test suite is passing(
bundle exec rspec
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
License
Copyright (c) 2015 Ably, Licensed under an MIT license. Refer to LICENSE.txt for the license terms.