Permalink
Browse files

Another big edit to the readme

  • Loading branch information...
1 parent 8284fd8 commit a88210070ef421fcf800b58fc465740ea8a63554 @mloughran mloughran committed Nov 12, 2012
Showing with 55 additions and 58 deletions.
  1. +55 −58 README.md
View
@@ -5,7 +5,6 @@ Pusher gem
## Configuration
-
After registering at <http://pusher.com> configure your app with the security credentials.
### Global
@@ -16,58 +15,47 @@ The most standard way of configuring Pusher is to do it globally on the Pusher c
Pusher.key = 'your-pusher-key'
Pusher.secret = 'your-pusher-secret'
+Global configuration will automatically be set from the `PUSHER_URL` environment variable if it exists. This should be in the form `http://KEY:SECRET@api.pusherapp.com/apps/APP_ID`. On Heroku this environment variable will already be set.
-TODO: what are all the configuration options?
-
-TODO: should we mention that Heroku apps are automatically configured?
-
-If you need to request over HTTP proxy, then you can configure the {Pusher#http_proxy}.
+If you need to make requests via a HTTP proxy then it can be configured
Pusher.http_proxy = 'http://(user):(password)@(host):(port)'
### Instantiating a Pusher client
-Sometime you may have multiple sets of API keys, or want different configuration in different parts of your application. In these scenarios, a pusher `client` can be configured:
+Sometimes you may have multiple sets of API keys, or want different configuration in different parts of your application. In these scenarios, a pusher `client` may be configured:
pusher_client = Pusher.new({
app_id: 'your-pusher-app-id',
key: 'your-pusher-key',
- secret: 'your
+ secret: 'your-pusher-secret'
})
This `client` will have all the functionality listed on the main Pusher class (which proxies to a client internally).
+
+
## Interacting with the Pusher service
The Pusher gem contains a number of helpers for interacting with the service. As a general rule, the library adheres to a set of conventions that we have aimed to make universal.
-### Raising errors
-
-By default, requests to our service that could return an error code, do not raise an exception, but do log. To rescue and inspect these errors, a separate version with an exclamation point exists, eg `trigger!`.
+### Handling errors
-Handle errors by rescuing `Pusher::Error` (all Pusher errors are descendants of this error)
+Handle errors by rescuing `Pusher::Error` (all errors are descendants of this error)
begin
- Pusher['a_channel'].trigger!('an_event', {:some => 'data'})
+ Pusher.trigger(['a_channel'], 'an_event', {:some => 'data'})
rescue Pusher::Error => e
# (Pusher::AuthenticationError, Pusher::HTTPError, or Pusher::Error)
end
### Logging
-Errors are logged to `Pusher.logger`. It will by default use `Logger` from stdlib, however you can assign any logger:
+Errors are logged to `Pusher.logger`. It will by default use `Logger` from the standard library, however you can assign any logger:
Pusher.logger = Rails.logger
-### Asyncronous requests
-
-The default method of interaction is synchronous. If you are running your application in an evented environment, you may want to use the asynchronous versions of the Pusher API methods to avoid blocking. The convention for this is to add the suffix `_async` to the method, eg `trigger_async`.
-
-When using an asyncronous version of a method, it will return a deferrable. An example of this is included towards the bottom of this document.
-
-TODO: does this mean that you can combine to form `trigger_async!`?
-
-## Publishing events
+### Publishing events
An event can be sent to Pusher in in the following ways:
@@ -81,19 +69,19 @@ Note: the first `channels` argument can contain multiple channels you'd like you
An optional fourth argument of this method can specify a `socket_id` that will be excluded from receiving the event (generally the user where the event originated -- see <http://pusher.com/docs/publisher_api_guide/publisher_excluding_recipients> for more info).
-### Original publisher API
+#### Original publisher API
Most examples and documentation will refer to the following syntax for triggering an event:
Pusher['a_channel'].trigger('an_event', {:some => 'data'})
-
-This will continue to work, but will be replaced as the canonical version by the first method that supports multiple channels.
-## Generic requests to the Pusher REST API
+This will continue to work, but will be replaced as the canonical version by `Pusher.trigger` which supports multiple channels.
-Aside from triggering events, our REST API also supports a number of operations for querying the state of the system. A reference of the available methods is available here <http://pusher.com/docs/rest_api>.
+### Generic requests to the Pusher REST API
-All requests must be signed by your secret key. Luckily, the Pusher gem provides a wrapper to this which makes requests much simpler. Examples are included below:
+Aside from triggering events, the REST API also supports a number of operations for querying the state of the system. A reference of the available methods is available at <http://pusher.com/docs/rest_api>.
+
+All requests must be signed by using your secret key, which is handled automatically using these methods:
# using the Pusher class
Pusher.get('url_without_app_id', params)
@@ -103,49 +91,58 @@ All requests must be signed by your secret key. Luckily, the Pusher gem provides
Note that you don't need to specify your app_id in the URL, as this is inferred from your credentials. As with the trigger method above, `_async` can be suffixed to the method name to return a deferrable.
-## Generating authentication responses
-
-The Pusher Gem also deals with signing requests to authenticate private or presence channels. The `authenticate` method is available on a channel object for this purpose and returns a JSON object that can be returned to the client that made the request. More information on this authentication scheme can be found in the docs on <http://pusher.com>
+### Asynchronous requests
-### Private channels
-
- Pusher['private-my_channel'].authenticate(params[:socket_id])
+If you are running your application in an evented environment, you may want to use the asynchronous versions of the Pusher API methods to avoid blocking. The convention for this is to add the suffix `_async` to the method, e.g. `trigger_async` or `post_async`.
-### Presence channels
+You need to be running eventmachine to make use of this functionality. This is already the case if, for example, you're deploying to Heroku or using the Thin web server. You will also need to add `em-http-request` to your Gemfile.
-These work in a very similar way, but require a unique identifier for the user being authenticated, and optionally some attributes that describe that allowed them to be identified in a more human friendly way (eg their name or gravatar):
+When using an asynchronous version of a method, it will return a deferrable.
- Pusher['presence-my_channel'].authenticate(params[:socket_id], {
- user_id: 'user_id',
- user_info: {} # optional
- })
+ Pusher.trigger_async(['a_channel'], 'an_event', {
+ :some => 'data'
+ }, socket_id).callback {
+ # Do something on success
+ }.errback { |error|
+ # error is a instance of Pusher::Error
+ }
-## Receiving WebHooks
-See {Pusher::WebHook}
+## Authenticating subscription requests
-TODO: I don't know why this doesn't have inline docs...
+It's possible to use the gem to authenticate subscription requests to private or presence channels. The `authenticate` method is available on a channel object for this purpose and returns a JSON object that can be returned to the client that made the request. More information on this authentication scheme can be found in the docs on <http://pusher.com>
-Asynchronous triggering
------------------------
+### Private channels
-To avoid blocking in a typical web application, you may wish to use the {Pusher::Channel#trigger_async} method which makes asynchronous API requests. `trigger_async` returns a deferrable which you can optionally bind to with success and failure callbacks.
+ Pusher['private-my_channel'].authenticate(params[:socket_id])
-You need to be running eventmachine to make use of this functionality. This is already the case if, for example, you're deploying to Heroku or using the Thin web server. You will also need to add `em-http-request` to your Gemfile.
+### Presence channels
- $ gem install em-http-request
+These work in a very similar way, but require a unique identifier for the user being authenticated, and optionally some attributes that are provided to clients via presence events:
- deferrable = Pusher['a_channel'].trigger_async('an_event', {
- :some => 'data'
- }, socket_id)
- deferrable.callback {
- # Do something on success
- }
- deferrable.errback { |error|
- # error is a instance of Pusher::Error
- }
+ Pusher['presence-my_channel'].authenticate(params[:socket_id], {
+ user_id: 'user_id',
+ user_info: {} # optional
+ })
+## Receiving WebHooks
+A WebHook object may be created to validate received WebHooks against your app credentials, and to extract events. It should be created with the `Rack::Request` object (available as `request` in Rails controllers or Sinatra handlers for example).
+
+ webhook = Pusher.webhook(request)
+ if webhook.valid?
+ webhook.events.each do |event|
+ case event["name"]
+ when 'channel_occupied'
+ puts "Channel occupied: #{event["channel"]}"
+ when 'channel_vacated'
+ puts "Channel vacated: #{event["channel"]}"
+ end
+ end
+ render text: 'ok'
+ else
+ render text: 'invalid', status: 401
+ end

0 comments on commit a882100

Please sign in to comment.