-
Notifications
You must be signed in to change notification settings - Fork 123
OAuth 2 Connector Example
The easiest way to get going is to copy and paste the code in Locker/Connectors/skeleton into a new directory for your connector. Let's pretend there isn't a yet a foursquare connector (we'll use "FoursquareExample" as the name so nothing bad happens):
cd Connectors
mkdir FoursquareExample
cd FoursquareExample
cp -r ../skeleton/* .The first thing we'll want to do is change the name of the .connector manifest file:
mv skeleton.connector FoursquareExample.connectorNow let's edit that file. The only things that MUST be changed are the handle, mongoCollections, and provides fields.
{
"title":"Foursquare Example",
"action":"Connect to a Foursquare account",
"desc":"Collect and sync my data from my Foursquare account",
"run":"node init.js",
"status":"unstable",
"handle":"foursquareexample",
"mongoCollections": ["friends"],
"provides":["contact/foursquareexample"]
}More info can be found about the provides field on the service types page.
Next let's take a look at the init.js file. The require('connector/client').init({...}) function loads the common connector bootstrap file and initializes it with some startup info - in this case it passes OAuth 2 settings. If your service uses OAuth 1.0, checkout the twitter connector for a well documented template. For username and password, see the Username and Password Auth section below.
For more details about the init.js file and client.init function, see the Custom Files section below.
Let's put foursquare info into the init.js file:
require('connector/client').init({"oauth2" :
{"provider" : "Foursquare",
"appIDName" : "Client ID",
"appSecretName" : "Client Secret",
"authEndpoint" : "authenticate",
"accessTokenResponse" : "json",
"endPoint" : "https://foursquare.com/oauth2/",
"linkToCreate" : "https://foursquare.com/oauth/register",
"grantType" : "authorization_code"}});Next, let's edit the sync.js file. Add some code to the existing syncItems function:
exports.syncItems = function(callback) {
//hit the friends API endpoint
request.get({uri:'https://api.foursquare.com/v2/users/self/friends?oauth_token=' + auth.accessToken},
function(err, resp, body) {
var json = JSON.parse(body);
//probably should check for errors here
addItems(json.response.friends.items, function() {
//repeat every hour
callback(err, 3600, "Updated " + json.response.friends.count + " friends");
});
});
}And then we'll create the addItems function:
function addItems(friends, callback) {
if(!friends || !friends.length) {
process.nextTick(callback);
return;
}
var friend = friends.shift();
dataStore.addObject('friends', friend, function(err) {
var eventObj = {source:'friends', type:'new', data:friend};
exports.eventEmitter.emit('contact/foursquareexample', eventObj);
addItems(friends, callback);
});
}At this point, the connector is in a functioning state, but if we'd like, we can tailor the sync-api.js file to represent what we are doing (if not, JMP Done!). Let's change the name of the /items endpoint to /updateFriends:
app.get('/items', items);becomes:
app.get('/updateFriends', updateFriends);and then we change the items function to updateFriends:
// this is the basic structure of an endpoint for something you'd be parsing.
function updateFriends(req, res) {
...
locker.at('/updateFriends', repeatAfter);
...
}and finally edit the html in the index function to point to /updateFriends instead of /items:
res.end("<html>found a token, load <a href='updateFriends'>friends</a>");Now we're ready to run.
cd ../..
node lockerd.js- Then open up the dashboard at http://localhost:8042 and navigate to the Services section.
- Click the "[show unstable]" link in the top right hand corner. "Foursquare Example" should now be listed as an installable connector.
- Click the Install Connector button.
The connector should now install and take you to the auth page. Follow the instructions from there.
You've made your first connector!