This add-on is operated by Ably
Simply better realtime for any enabled device
Ably
Last updated October 02, 2023
Table of Contents
- Provisioning the Heroku add-on
- Accessing your Ably dashboard
- Using the Ably JavaScript (browser or Node.js) client library
- Using the Ably Ruby client library
- Using the Ably PHP REST client library
- Using the Ably Python REST client library
- Using the Ably Java client library
- Support
- Next steps
- Removing the Ably add-on
Ably Ably is a realtime data delivery platform.
We provide the infrastructure, services and support to make it easy for you to add realtime experiences to your apps, websites and any other internet connected device. Ably is architected to be reliable. So reliable, in fact, that we offer a 100% data delivery guarantee.
Customers use Ably to provide limitless scale and global performance for their realtime chat, games, live streaming, betting and financial apps. See examples of Ably in use.
Provisioning the Heroku add-on
Ably can be attached to a Heroku application via the Dashboard, or the CLI:
A list of all plans available can be found here.
$ heroku addons:create ably:bootstrap
Once Ably has been added, the ABLY_API_KEY
setting will be available in the app configuration. Find out more about Ably API keys. This can be confirmed using the heroku config:get
command.
$ heroku config:get ABLY_API_KEY
6pdNVA.p11x45:SeTwcAAP4EC7wIi
After installing Ably the application should be configured to fully integrate with the add-on.
Accessing your Ably dashboard
From within your Ably dashboard, you can view and access your live statistics, set up and manage API keys, configure channel rules and webhooks, and use the Ably developer console.
The dashboard can be accessed via the CLI:
$ heroku addons:open ably
Opening ably for sharp-mountain-4005
or by visiting the Heroku Dashboard and selecting the application in question. Select Ably from the Add-ons menu.
You will then be taken to your app dashboard
Using the Ably JavaScript (browser or Node.js) client library
For node.js
Installation from npm
$ npm install ably
Usage
For the realtime library:
var realtime = require('ably').Realtime;
For the rest-only library:
var rest = require('ably').Rest;
For browsers
Include the Ably library in your HTML:
<script src="https://cdn.ably.io/lib/ably.min-1.js"></script>
For the realtime library:
var realtime = Ably.Realtime;
For the rest-only library:
var rest = Ably.Rest;
JavaScript example
This example demonstrates a straightforward way to publish and receive a message on a channel. See the Ably Realtime client library documentation for complete usage.
var apiKey = process.env['ABLY_API_KEY'];
/* API key available in Heroku Node.js, we recommend token auth in the browser */
var client = new Ably.Realtime({ key: apiKey });
var channel = client.channels.get('test');
channel.subscribe(function(message) {
message.name // 'greeting'
message.data // 'Hello World!'
});
channel.publish('greeting', 'Hello World!');
Using the Ably Ruby client library
The client library is available as a gem from RubyGems.org.
Add this line to your application’s Gemfile:
gem 'ably'
And then install this Bundler dependency:
$ bundle
Or install it yourself as:
$ gem install ably
Ruby Realtime API example
This example, which runs under the asynchronous evented EventMachine library, demonstrates a straightforward way to publish and receive a message on a channel. See the Ably Realtime client library documentation for complete usage.
EventMachine.run do
client = Ably::Realtime.new(key: ENV['ABLY_API_KEY'])
channel = client.channels.get('test')
channel.subscribe do |message|
message.name #=> "greeting"
message.data #=> "Hello World!"
end
channel.publish('greeting', 'Hello World!')
end
Ruby REST API example
This example demonstrates a straightforward way to publish a message over REST on a channel. See the Ably REST client library documentation for complete usage.
client = Ably::Rest.new(key: ENV['ABLY_API_KEY'])
channel = client.channels.get('test')
channel.publish('greeting', 'Hello World!')
Using the Ably PHP REST client library
The client library is available as a composer package on packagist. Install composer if you don’t have it.
Install Ably from the shell with:
$ composer require ably/ably-php --update-no-dev
Omit the --update-no-dev
parameter, if you want to run tests. Then simply require composer’s autoloader:
require_once __DIR__ . '/../vendor/autoload.php';
PHP REST API example
This example demonstrates a straightforward way to publish a message over REST on a channel. See the Ably REST client library documentation for complete usage.
$client = new Ably\AblyRest($_ENV["ABLY_API_KEY"]);
$channel = $client->channel('test');
$channel->publish('myEvent', 'Hello!');
``
channel.publish('greeting', 'Hello World!')
Using the Ably Python REST client library
The client library is available as a PyPI package.
Installing From PyPI
$ pip install ably
Installing Locally
$ git clone https://github.com/ably/ably-python.git
$ cd ably-python
$ python setup.py install
Python REST API example
This example demonstrates a straightforward way to publish a message over REST on a channel. See the Ably REST client library documentation for complete usage.
from ably import AblyRest
client = AblyRest(os.environ['ABLY_API_KEY'])
channel = client.channels.get('channel_name')
channel.publish('event', 'message')
Using the Ably Java client library
The Realtime library for Java is downloadable as a JAR at our GitHub releases page. You can either download the full JAR which includes all dependencies, or just the library but it will be your responsibility to ensure all dependencies are met. Please see the GitHub repo for the latest installation instructions.
Java Realtime example
This example demonstrates a straightforward way to publish and receive a message on a channel. See the Ably Realtime client library documentation for complete usage.
String apiKey = System.getenv("ABLY_API_KEY");
AblyRealtime ably = new AblyRealtime(apiKey);
Channel channel = ably.channels.get("test");
channel.subscribe(new MessageListener() {
@Override
public void onMessage(Message[] messages) {
for(Message message : messages) {
System.out.println("Received `" + message.name + "` message with data: " + message.data);
}
}
});
channel.publish("greeting", "Hello World!");
Java REST API example
This example demonstrates a straightforward way to publish a message over REST on a channel. See the Ably REST client library documentation for complete usage.
String apiKey = System.getenv("ABLY_API_KEY");
AblyRest ably = new AblyRest(apiKey);
Channel channel = ably.channels.get("test");
channel.publish("event", "message");
Support
We have a host of engineers available to help you if have any questions or problems. Visit the Ably support site that includes live chat.
We also have a host of documentation and examples available:
- Quickstart guide
- Examples
- How Ably works
- Realtime library documentation
- REST library documentation
- Authentication explained
If you believe there is a disruption or problem with the service, visit the Ably status site.
Next steps
Ably provides a straightforward API to publish and receive messages on channels over WebSockets. However, our feature set is much broader than simply pub/sub providing access to Mobile and browser push notifications, Presence and device status, Message history, End-to-End Encryption, Statistics, WebHooks and a rich authentication system.
We recommend you read the documentation or get in touch with our team if you have any questions.
Removing the Ably add-on
Removing the Ably add-on will destroy all channel history, API keys, channel rules and app configuration. This cannot be undone!
Ably can be removed via the CLI:
$ heroku addons:destroy ably
Destroying ably-adjacent-53647 on test-ably-addon... done, (free)