Superfeedr Add-on

This addon allows you to interact with Superfeedr's API and receive realtime RSS feed notifications. If you're application needs to grab some content from a 3rd party site through their RSS feeds, this add-on will make that easy for you.

Local setup

There should be no significant change in your local environment. Just install the addon as explained below and get the credentials with:

$ heroku config // You need SUPERFEEDR_LOGIN and SUPERFEEDR_PASSWORD

Beware though, as Superfeedr will "shard" the traffic between different connections : if you have 2 instances of the application running concurrently, both will get some of the data, so we usually recommend that you use other credentials while in development and/or testing. Create a Superfeedr subscriber account.

Deploying to Heroku

To use superfeedr on Heroku, install the superfeedr add-on:

$ heroku addons:add superfeedr

Setup

There are several ways to implement Superfeedr inside your application. Feel free to read Superfeedr's documentation to learn more.

We are providing 2 examples, one with Node.js that uses our XMPP API, and one in Ruby which uses our PubSubHubbub API. Both approaches have advantages, so chose wisely.

Node.js

This integration uses Julien Genestoux's NPM module for Superfeedr. It is using Superfeedr's XMPP API, but does so directly inside your web application, you won't need to run any extra Proc to achieve this.

First, make sure you add "superfeedr": ">=0.0.3" in the dependencies section of your package.json.

Then, somewhere in your application, require Superfeedr:

var superfeedr = require('superfeedr').Superfeedr;

Make sure you connect to Superfeedr using your credentials:

client = new superfeedr(process.env.SUPERFEEDR_LOGIN, process.env.SUPERFEEDR_PASSWORD);
// The connected event is triggered when your app is connected to Superfeedr.
client.on('connected', function() {
    console.log("Connected!");
    // You can then subscribe to feeds
    client.subscribe("http://superfeedr.com/track/music", function(err, feed) {
        console.log("Susbcribed");
    });
});

You can then process incoming notifications like this :

client.on('notification', function(notification) {
    // Here you should process the notification, save the new entries in the database, send them
    // over to the browser... etc
});

That's it!

If you want a full blown example, check out this source on Github.

Warning: Heroku sometimes idles single-dyno web applications when they have long periods of inactivity. If this happens, your Superfeedr connection will be dropped and you may miss events. There are several ways to avoid this: add an extra dyno or run the client in a worker or use a service like pingdom which will trigger requests to your application on a regular basis, thus avoiding idling.

Ruby

This integration uses the Superfeedr Rack Middleware gem. This gem uses Superfeedr's PubSubHubbub API. The benefit of this is that it integrates directly (and deeply) in your web application, without requiring the use of an additional Proc.

First, do not forget to add gem 'rack-superfeedr' to your Gemfile and bundle install it, or install the gem directly using gem install rack-superfeedr

The Superfeedr Rack middleware requires a bit of configuration:

use Rack::Superfeedr, { :host => "<yourapp>.heroku.com", :login => ENV['SUPERFEEDR_LOGIN'], :password => ENV['SUPERFEEDR_PASSWORD'], :format => "json", :async => true } do |superfeedr|
  Superfeedr = superfeedr
end

If you want to use this application locally, please use a tool like showoff which will bridge requests to your local machine, and don't forget to set the right :host param.

You can then easily use the Superfeedr object in your application to subscribe to feeds,

Superfeedr.subscribe("http://push-pub.appspot.com/feed")

Unsubscribe,

Superfeedr.unsubscribe("http://push-pub.appspot.com/feed")

and handle incoming notification:

Superfeedr.on_notification do |notification|
    puts notification.to_s # You probably want to persist that data in some kind of data store...
end

To debug things on your end, we suggest you subscribe to the feed at http://push-pub.appspot.com/feed and then publish new entries in it with the web application http://push-pub.appspot.com/. You should see incoming notifications right after you added a new entry.

If you want a complete example, please check this one, and don't forget to read the docs for more complex settings and use cases.

superfeedr/heroku-addon-documentation.md