node-fastpass

A node.js library for getsatisfaction fastpass (single sign-on)

This serves as a drop-in replacement for the existing getsatisfaction fastpass libraries, and implements the same method signatures (with some defaulting for ease of use) as the ruby library. Documentation for existing fastpass libraries can be found on the getsatisfaction help site.

Usage:

Add the dependency:

npm install --save fastpass

Require it:

var FastPass = require('fastpass')

Instantiate it:

var fastPass = new FastPass({
   // optional, defaults to "getsatisfaction.com"
   domain : "getsatisfaction.com",
   // required, your consumer key
   consumer_key : "xi2vaxgpp06m",
   // required, your consumer secret
   consumer_secret : "ly68der0hk8idfr5c73ozyq56jpwstd1",
   // optional at instantiation - email of the user
   email : "[email protected]",
   // optional at instantiation - Name of the user
   name : "Scott",
   // optional at instantiation - unique ID of user (must stay the same for the lifetime the user in your system)
   unique_identifier : "nullstyle",
   // optional boolean, defaults to false
   is_secure : false,
   // optional object, any private fields you like. defaults to {}.
   private_fields : {}
})

Implementation:

Using the Script tag

fastPass.script({
  email : "[email protected]",
  name : "Scott",
  unique_identifier : "nullstyle"
}, function(err,script){
  var outputScript = script
})

or if you passed name, unique_identifier, and email at instantiation:

fastPass.script(function(err,script){
  var outputScript = script
})

Now replace all links to getSatisfaction with calls to GSFN.goto_gsfn()

// for instance, in jQuery
$('body').on('click','a[href="http://getsatisfaction.com"]',function(){ GSFN.goto_gsfn(); return false; })

Using Cookies along with CNAME

Set a cookie named "fastpass" to the URL generated by the FastPass library. Note: This is only available if your company is using the CNAME feature.

// inside of an express route or whatever:
fastPass.url(<options>,function(err,url){
  cookies["fastpass"] = url
})

Using the Query String

Include the generated URL in the param named "fastpass" in all links to Get Satisfaction.

// in some template context
fastPass.url(<options>,function(err,url){
  var linkUrl = "<a href="http://getsatisfaction.com/mycompany?fastpass=" + url + ">Our Support Community</a>"
})

Option Details:

Field         |  Required  |  Notes
Key           |    Yes     |
Secret        |    Yes     |
Email         |    Yes     |
Name          |    Yes     |
Unique Id     |    Yes     | Must remain unchanged for the lifetime of the user's account in your system.
Is Secure     |    No      | (defaults to false)
Private Fields|    No      | Key/value pairs to send along with the user to Get Satisfaction.

Example Setup:

The getSatisfaction setup is bi-directional, the smoothest sign on process happens when you have a CNAME set, a cookie with the current user, and a GSFN script on the page after login.

In an express server, here's how that might look:

// Assumes that you've require'd and instantiated FastPass with your credentials.
// a-la: var fastPass = new FastPass(<options>)

// getsatisfaction middleware
// assumes that you've got authentication middleware before this that sets `req.authenticated` and adds `user` to `req.session`.
// these assumptions can obviously be replaced by however your app works, this should get you most of the way there.
app.use(function(req,res,next){
  if(req.authenticated){
    // add a cookie for getSatisfaction single sign on
    // crudely strips the subdomain - probably should be smarter to avoid clobbering non-subdomain urls.
    var cookieDomain = req.headers.host.replace('^[^\.]*',''),
        user = req.session.user
    fastPass.url({name : user.first_name + " " + user.last_name, email : user.email, unique_identifier : user.id },function(err,url){
      // this is the important part - sets a cookie for your domain.
      res.cookie('fastpass',url, {domain : cookieDomain})
      next()
    })
  } else {
    next()
  }
})

You'll also need to expose the script on all your logged-in pages:

app.get('/some/logged/in/route',function(req,res){
  var user = req.session.user
  fastPass.script({name : user.first_name + " " + user.last_name, email : user.email, unique_identifier : user.id },function(err,script){
    // do your res.send() or whatever, render the script
  })
})