Ably

A Ruby client library for ably.io, the realtime messaging service.

Documentation

Visit https://www.ably.io/documentation for a complete API reference and more examples.

Installation

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

Using the Realtime API

Introduction

All examples must be run within an EventMachine reactor as follows:

EventMachine.run do
  # ...
end

All examples assume a client has been created using one of the following:

# basic auth with an API key
client = Ably::Realtime.new(key: 'xxxxx')

# using token auth
client = Ably::Realtime.new(token: 'xxxxx')

If you do not have an API key, sign up for a free API key now

Connection

Successful connection:

client.connection.connect do
  # successful connection
end

Failed connection:

connection_result = client.connection.connect
connection_result.errback = Proc.new do
  # failed connection
end

Subscribing to connection state changes:

client.connection.on do |state_change|
  state_change.current #=> :connected
  state_change.previous #=> :connecting
end

Subscribing to a channel

Given a channel is created as follows:

channel = client.channels.get('test')

Subscribe to all events:

channel.subscribe do |message|
  message.name #=> "greeting"
  message.data #=> "Hello World!"
end

Only certain events:

channel.subscribe('myEvent') do |message|
  message.name #=> "myEvent"
  message.data #=> "myData"
end

Publishing a message to a channel

channel.publish('greeting', 'Hello World!')

Querying the History

channel.history do |messages_page|
  messages_page #=> #<Ably::Models::PaginatedResult ...>
  messages_page.items.first # #<Ably::Models::Message ...>
  messages_page.items.first.data # payload for the message
  messages_page.items.length # number of messages in the current page of history
  messages_page.next do |next_page|
    next_page #=> the next page => #<Ably::Models::PaginatedResult ...>
  end
  messages_page.has_next? # false, there are more pages
end

Presence on a channel

channel.presence.enter(data: 'metadata') do |presence|
  presence.get do |members|
    members #=> [Array of members present]
  end
end

Subscribing to presence events

channel.presence.subscribe do |member|
  member #=> { action: :enter, client_id: 'bob' }
end

Querying the Presence History

channel.presence.history do |presence_page|
  presence_page.items.first.action # Any of :enter, :update or :leave
  presence_page.items.first.client_id # client ID of member
  presence_page.items.first.data # optional data payload of member
  presence_page.next do |next_page|
    next_page #=> the next page => #<Ably::Models::PaginatedResult ...>
  end
  presence_page.has_next? # false, there are more pages
end

Symmetric end-to-end encrypted payloads on a channel

When a 128 bit or 256 bit key is provided to the library, all payloads are encrypted and decrypted automatically using that key on the channel. The secret key is never transmitted to Ably and thus it is the developer's responsibility to distribute a secret key to both publishers and subscribers.

secret_key = Ably::Util::Crypto.generate_random_key
channel = client.channels.get('test', cipher: { key: secret_key })
channel.subscribe do |message|
  message.data #=> "sensitive data (encrypted before being published)"
end
channel.publish "name (not encrypted)", "sensitive data (encrypted before being published)"

Using the REST API

Introduction

Unlike the Realtime API, all calls are synchronous and are not run within an EventMachine reactor.

All examples assume a client and/or channel has been created as follows:

client = Ably::Rest.new(key: 'xxxxx')
channel = client.channel('test')

Publishing a message to a channel

channel.publish('myEvent', 'Hello!') #=> true

Querying the History

messages_page = channel.history #=> #<Ably::Models::PaginatedResult ...>
messages_page.items.first #=> #<Ably::Models::Message ...>
messages_page.items.first.data # payload for the message
messages_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>
messages_page.has_next? # false, there are more pages

Current presence members on a channel

members_page = channel.presence.get # => #<Ably::Models::PaginatedResult ...>
members_page.items.first # first member present in this page => #<Ably::Models::PresenceMessage ...>
members_page.items.first.client_id # client ID of first member present
members_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>
members_page.has_next? # false, there are more pages

Querying the presence history

presence_page = channel.presence.history #=> #<Ably::Models::PaginatedResult ...>
presence_page.items.first #=> #<Ably::Models::PresenceMessage ...>
presence_page.items.first.client_id # client ID of first member
presence_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>

Symmetric end-to-end encrypted payloads on a channel

secret_key = Ably::Util::Crypto.generate_random_key
channel = client.channels.get('test', cipher: { key: secret_key })
channel.publish nil, "sensitive data" # data will be encrypted before publish
messages_page = channel.history
messages_page.items.first.data #=> "sensitive data"

Generate a Token

Tokens are issued by Ably and are readily usable by any client to connect to Ably:

token_details = client.auth.request_token
# => #<Ably::Models::TokenDetails ...>
token_details.token # => "xVLyHw.CLchevH3hF....MDh9ZC_Q"
client = Ably::Rest.new(token: token_details)

Generate a TokenRequest

Token requests are issued by your servers and signed using your private API key. This is the preferred method of authentication as no secrets are ever shared, and the token request can be issued to trusted clients without communicating with Ably.

token_request = client.auth.create_token_request(ttl: 3600, client_id: 'jim')
# => {"id"=>...,
#     "clientId"=>"jim",
#     "ttl"=>3600,
#     "timestamp"=>...,
#     "capability"=>"{\"*\":[\"*\"]}",
#     "nonce"=>...,
#     "mac"=>...}

client = Ably::Rest.new(token: token_request)

Fetching your application's stats

stats_page = client.stats #=> #<Ably::Models::PaginatedResult ...>
stats_page.items.first = #<Ably::Models::Stats ...>
stats_page.next # retrieves the next page => #<Ably::Models::PaginatedResult ...>

Fetching the Ably service time

client.time #=> 2013-12-12 14:23:34 +0000

Dependencies

If you only need to use the REST features of this library and do not want EventMachine as a dependency, then you should consider using the Ably Ruby REST gem.

Support, feedback and troubleshooting

Please visit http://support.ably.io/ 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 of Bundler, see the CHANGELOG.

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

Ably

Documentation

Installation

Using the Realtime API

Introduction

Connection

Subscribing to a channel

Publishing a message to a channel

Querying the History

Presence on a channel

Subscribing to presence events

Querying the Presence History

Symmetric end-to-end encrypted payloads on a channel

Using the REST API

Introduction

Publishing a message to a channel

Querying the History

Current presence members on a channel

Querying the presence history

Symmetric end-to-end encrypted payloads on a channel

Generate a Token

Generate a TokenRequest

Fetching your application's stats

Fetching the Ably service time

Dependencies

Support, feedback and troubleshooting

Contributing

License