How to Add Rapportive to Your App in 30 Minutes

By Dan Lynn

Rapportive is great--especially for someone like me who forgets names constantly. The little sidebar that sits in your gmail window gives you a lot of useful information about the person who wrote you an email. It shows you a photo, job title, company, social network usernames, and much more. It’s a great tool, but wouldn’t it be even better to have that functionality everywhere…like in your app?

Rapportive should be everywhere!

Quite a few kinds of software let users interact with each other. There are help desk systems, CRMs, chat systems, social networks, forums, you name it. If your app is at all like these, there is a huge opportunity for you to stand out from the crowd by adding-in simple Rapportive-like augmentation to your user profiles or contact records.

My name is Dan Lynn. I’m a co-founder of FullContact, and we started the company with this goal in mind. After a couple years of iteration, we've made it quite easy for you to add rich user profiles into your app.

Start with a simple Node.js chat app

For this post, let’s add some user photos into a simple websockets-powered chat application. I decided to base this how-to off Gabriel Manricks' great "Working with data in Sails.js" Tuts+ tutorial. It uses Sails, a great NodeJS web framework (I use the term framework very lightly) to get you productive quickly but not tie your hands with a bunch of opinionated architecture. Sails is powered by Express, socket.io and a few other must-haves.

If you want to follow along, go ahead and clone my fork of the repo and checkout the first change, then run the app:

Note: this assumes that you’ve installed Node.js, which includes npm (shorthand for "node package manager").

This branch shows the repo immediately after I made the changes necessary to track “currently signed-in” users. To do this, I simply save a new CurrentUsers record when a user signs up or signs in and I destroy the record when the user signs out. For both of these I’m using Sails’ built-in pubsub functionality to keep the clients’ views in sync with the server’s.

At this point, if you run the app. You should be able to sign up a user (make sure to use an email address for the username) and start chatting. Try doing this in a few different browsers with different users and you’ll see the websockets in action. Note that when a new users signs in, other signed-in users immediately see the new user “join” the room.

Pretty cool, huh? I bet it would be cooler with some user photos.

Integrate The FullContact API

Now let’s try using the FullContact API. There are about five steps:

  1. Get yourself a FullContact API key.
  2. Sign up for a free Runscope account. We’ll be using FullContact’s webhooks feature and since you’ll be running your Sails app locally, FullContact will need a way to send webhooks to your computer. Runscope Passageway is a very elegant way to this. Download the appropriate binary for your computer and run it with the bucket ID that Runscope gives you.
  3. Checkout my changes to work with the FullContact API and delete your previous users database since this branch adds fields to the Users and CurrentUsers models.
  4. Edit the “config/fullcontact.js” and enter your Runscope Passageway url in the passageWayPrefix field and enter your FullContact API key in the apiKey field.
  5. Run the app again by typing sails lift. Sign up users again (using real email addresses for the username). You will now see photos appearing shortly after a new user signs in!

Much better with photos

.

The Details

First, we send an enrichment request to the FullContact API with the user’s email address, and we give FullContact a URL that it can send the results to. This webhook style is a bit more complex than a simple GET request, but it’s worth it because FullContact can take some extra time to make sure to find the freshest information possible. Let’s walk through how to set this up.

We’ll need to create a new service in Sails and invoke an enrich function when a new user signs up:

Note that the call to FullContact includes four parameters. The email parameter is the email address you’d like more information about (although FullContact supports lookups by twitter and facebookUsername too). The apiKey parameter authenticates your request (make sure you get an API key here). The webhookUrl parameter contains the URI-encoded URL that FullContact should send the response to, and the webhookBody=json parameter tells FullContact that you prefer to receive the response in JSON format (by default, it is application/x-www-form-urlencoded).

For our webhookUrl, we’re using a new Sails controller called FullContactController. It has one function, called webhook, and we route the /fullcontact/:userId path to it. It simply tries to find a primary photo for the user, then looks up the user in both the Users store and the CurrentUsers store and updates them both by adding a photoUrl. The last step is to call CurrentUsers.publishUpdate(), which notifies connected clients that the user object has changed.

After we have this built, we just need to update our view code to receive the updates.

I'll leave this as an exercise for the reader. If you're not familiar with Sails and/or Backbone, I highly recommend that you go through Gabriel's tutorial.

Thanks for checking out this post! I'd love to get your feedback on it. We're always looking for ways to make it easier for developers to get started using FullContact, and your feedback is important. And if you find problems like these interesting, FullContact is hiring!