lib/submodules/ably-ruby/README.md in ably-rest-0.7.5 vs lib/submodules/ably-ruby/README.md in ably-rest-0.8.1
- old
+ new
@@ -1,15 +1,16 @@
-# [Ably](https://ably.io)
+# [Ably](https://www.ably.io)
[](https://travis-ci.org/ably/ably-ruby)
[](http://badge.fury.io/rb/ably)
+[](https://coveralls.io/r/ably/ably-ruby)
-A Ruby client library for [ably.io](https://ably.io), the real-time messaging service.
+A Ruby client library for [ably.io](https://www.ably.io), the realtime messaging service.
## Documentation
-Visit https://ably.io/documentation for a complete API reference and more examples.
+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](https://rubygems.org/gems/ably).
@@ -38,11 +39,15 @@
```
All examples assume a client has been created as follows:
```ruby
-client = Ably::Realtime.new(api_key: "xxxxx")
+# basic auth with an API key
+client = Ably::Realtime.new(key: 'xxxxx')
+
+# using token auth
+client = Ably::Realtime.new(token: 'xxxxx')
```
### Connection
Successful connection:
@@ -65,11 +70,11 @@
### Subscribing to a channel
Given:
```ruby
-channel = client.channel("test")
+channel = client.channel('test')
```
Subscribe to all events:
```ruby
@@ -80,30 +85,32 @@
```
Only certain events:
```ruby
-channel.subscribe("myEvent") do |message|
+channel.subscribe('myEvent') do |message|
message[:name] #=> "myEvent"
message[:data] #=> "myData"
end
```
### Publishing to a channel
```ruby
-channel.publish("greeting", "Hello World!")
+channel.publish('greeting', 'Hello World!')
```
### Querying the History
```ruby
-channel.history do |messages|
- messages # Ably::Models::PaginatedResource
- messages.first # Ably::Models::Message
- messages.length # number of messages in the retrieved history page
- messages.next_page # Ably::Models::PaginatedResource
+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
@@ -114,15 +121,15 @@
```
### Querying the Presence History
```ruby
-channel.presence.history do |presence_messages|
- presence_messages.first.action # Any of :enter, :update or :leave
- presence_messages.first.client_id
- presence_messages.first.data
- presence_messages.next_page # Ably::Models::PaginatedResource
+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
@@ -131,45 +138,58 @@
Unlike the Realtime API, all calls are synchronous and are not run within an [EventMachine](https://github.com/eventmachine/eventmachine) [reactor](https://github.com/eventmachine/eventmachine/wiki/General-Introduction).
All examples assume a client and/or channel has been created as follows:
```ruby
-client = Ably::Rest.new(api_key: "xxxxx")
+client = Ably::Rest.new(key: 'xxxxx')
channel = client.channel('test')
```
### Publishing a message to a channel
```ruby
-channel.publish("myEvent", "Hello!") #=> true
+channel.publish('myEvent', 'Hello!') #=> true
```
### Querying the History
```ruby
-channel.history #=> #<Ably::Models::PaginatedResource ...>
+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
```ruby
-channel.presence.get # => #<Ably::Models::PaginatedResource ...>
+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
```ruby
-channel.presence.history # => #<Ably::Models::PaginatedResource ...>
+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
```ruby
-client.auth.request_token
-# => #<Ably::Models::Token ...>
+token_details = client.auth.request_token
+# => #<Ably::Models::TokenDetails ...>
+token_details.token # => "xVLyHw.CLchevH3hF....MDh9ZC_Q"
+client = Ably::Rest.new(token: token_details.token)
-client.auth.create_token_request
+token = client.auth.create_token_request
# => {"id"=>...,
# "clientId"=>nil,
# "ttl"=>3600,
# "timestamp"=>...,
# "capability"=>"{\"*\":[\"*\"]}",
@@ -178,10 +198,18 @@
```
### Fetching your application's stats
```ruby
-client.stats #=> PaginatedResource [{:channels=>..., :apiRequests=>..., ...}]
+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
+
+```ruby
+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](https://rubygems.org/gems/ably-rest).