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 as follows:

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

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

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 a channel

Given:

channel = client.channel('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 to a channel

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

Querying the History

channel.history do |messages_page|
  messages_page #=> #<Ably::Models::PaginatedResource ...>
  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 # retrieves the next page => #<Ably::Models::PaginatedResource ...>
  messages_page.has_next? # false, there are more pages
end

Presence on a channel

channel.presence.enter(data: 'john.doe') do |presence|
  presence.get #=> [Array of members present]
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 # retrieves the next page => #<Ably::Models::PaginatedResource ...>
end

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::PaginatedResource ...>
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::PaginatedResource ...>
messages_page.has_next? # false, there are more pages

Presence on a channel

members_page = channel.presence.get # => #<Ably::Models::PaginatedResource ...>
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::PaginatedResource ...>
members_page.has_next? # false, there are more pages

Querying the Presence History

presence_page = channel.presence.history #=> #<Ably::Models::PaginatedResource ...>
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::PaginatedResource ...>

Generate Token and Token Request

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

token = client.auth.create_token_request
# => {"id"=>...,
#     "clientId"=>nil,
#     "ttl"=>3600,
#     "timestamp"=>...,
#     "capability"=>"{\"*\":[\"*\"]}",
#     "nonce"=>...,
#     "mac"=>...}

Fetching your application's stats

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

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 use the Ably Ruby REST gem.

Support and feedback

Please visit https://support.ably.io/ for access to our knowledgebase and to ask for any assistance.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Ensure you have added suitable tests and the test suite is passing(bundle exec rspec)
5. Push to the branch (git push origin my-new-feature)
6. Create a new Pull Request

License

Copyright (c) 2015 Ably, Licensed under an MIT license. Refer to LICENSE.txt for the license terms.