Superfeedr

This add-on is operated by Notifixious

Real-time feed parsing.

Superfeedr

Last Updated: 19 March 2014

The Superfeedr add-on is currently in beta.

Table of Contents

Introduction

This addon allows you to interact with Superfeedr’s API and receive realtime RSS and ATOM feed notifications. If your application needs to grab some content from a 3rd party site through their RSS feeds, this add-on will make that easy for you. Please note that Superfeedr also supports abritrary contents, like JSON or even HTML. You can get all that content pushed to your application really easily and won’t need to scrap the web :)

Choice of API

Superfeedr provides 2 distinct APIs: PubSubHubbub or XMPP PubSub. Please choose either of those wisely.

The XMPP PubSub API’s main advantage is that it can run with the exact same configuration and code in production and development. However, it may require you to use an additional Dyno (process) and your language of choice may not have excellent XMPP librairies.

The PubSubHubbub API uses webhooks, which means it will perform and handle HTTP requests, which is exactly what most Heroku apps are good at. However, if you want to develop locally, you need to make sure that your development machine is located outside the firewall as Superfeedr will need to be able to perform HTTP requests.

Feel free to reach out to help@superfeedr.com if you need help to pick the right one for you.

Local setup

Even though Heroku makes it really simple to provision Superfeedr accounts for your production environment, it doesn’t provide much for your development environment.

We strongly suggest that you do not share the Superfeedr credentials between your production and local/development environment, to avoid any conflict. 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. Please remember that you could as well use the PubSubHubbub API, as this other nodejs application does for example.

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("Subscribed");
    });
});

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 sleeps applications with a single web dyno when have been inactive for 1 hour. If this happens, your Superfeedr connection will be dropped and you may miss events. There are a few ways to avoid this: add an extra web dyno, or run the client in a worker.

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.

Further reading: