A client-side Javascript SDK for authenticating with OAuth2 (and OAuth1 with a oauth proxy) web services and querying their REST API's. HelloJS standardizes paths and responses to common API's like Google Data Services, Facebook Graph and Windows Live Connect. Its modular so that list is growing. No more spaghetti code!
Looking for more? HelloJS supports a lot more actions than just getting the users profile. Like, matching users with a users social friends list, sharing events with the users social streams, accessing and playing around with a users photos. Lets see if these whet your appetite ...
Windows | More.. | |||
---|---|---|---|---|
Profile: name, picture (email) | ✓ | ✓ | ✓ | |
Friends/Contacts: name, id (email) | ✓ | ✓ | ✓ | |
Albums, name, id, web link | ✓ | ✓ | ✓ | |
Photos in albums, names, links | ✓ | ✓ | ✓ | |
Photo file: url, dimensions | ✓ | ✓ | ✓ | |
Create a new album | ✓ | ✓ | ||
Upload a photo | ✓ | ✓ | ||
Delete an album | ✓ | ✗ | ||
Status updates | ✗ | ✓ | ✓ | |
Update Status | ✓ | ✓ | ✗ |
Items marked with a ✓ are fully working and can be tested here. Items marked with a ✗ aren't provided by the provider at this time. Blank items are work in progress, but there is good evidence that they can be done. Anything not listed i have no knowledge of and would appreciate input.
Download: HelloJS | HelloJS (minified)
Compiled source, which combines all the modules can be obtained from Github, and source files can be found in Source.
# Install the package manager, bower
npm install bower
# Install hello
bower install hello
The Bower package shall install the aforementioned "/src" and "/dist" directories. The "/src" directory provides individual modules which can be packaged as desired.
Note: Some services require OAuth1 or server-side OAuth2 authorization. In such case HelloJS communicates with an OAuth Proxy.
Quick start shows you how to go from zero to loading in the name and picture of a user, like in the demo above.
- Register your app domain
- Include hello.js script
- Create the signin buttons
- Setup listener for login and retrieve user info.
- Initiate the client_ids and all listeners
Register your application with atleast one of the following networks. Ensure you register the correct domain as they can be quite picky
- Windows Live (click on dashboard)
- Google +
<script class="pre" src="./dist/hello.all.min.js"></script>
Just add onclick events to call hello( network ).login(). Style your buttons as you like, i've used zocial css, but there are many other icon sets and fonts
<button onclick="hello( 'windows' ).login()">windows</button>
Lets define a simple function, which will load a user profile into the page after they signin and on subsequent page refreshes. Below is our event listener which will listen for a change in the authentication event and make an API call for data.
hello.on('auth.login', function(auth){
// call user information, for the given network
hello( auth.network ).api( '/me' ).success(function(r){
var $target = $("#profile_"+ auth.network );
if($target.length==0){
$target = $("<div id='profile_"+auth.network+"'></div>").appendTo("#profile");
}
$target.html('<img src="'+ r.thumbnail +'" /> Hey '+r.name).attr('title', r.name + " on "+ auth.network);
});
});
Now let's wire it up with our registration detail obtained in step 1. By passing a [key:value, ...] list into the hello.init
function. e.g....
hello.init({
facebook : FACEBOOK_CLIENT_ID,
windows : WINDOWS_CLIENT_ID,
google : GOOGLE_CLIENT_ID
},{redirect_uri:'redirect.html'});
That's it. The code above actually powers the demo at the start so, no excuses.
Initiate the environment. And add the application credentials
name | type | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
credentials |
object( key => value, ... )
| ||||||||||||||||||
options | set's default options, as in hello.login() |
hello.init({
facebook : '359288236870',
windows : '000000004403AD10'
});
If a network string is provided: A consent window to authenticate with that network will be initiated. Else if no network is provided a prompt to select one of the networks will open. A callback will be executed if the user authenticates and or cancels the authentication flow.
name | type | example | description | argument | default | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
network | string | windows, | One of our services. | required | null | ||||||||||||||||||||||||||||||||||||
options |
object
| ||||||||||||||||||||||||||||||||||||||||
callback | function | function(){alert("Logged
in!");} | A callback when the users session has been initiated | optional | null |
hello( "facebook" ).login( function(){
alert("You are signed in to Facebook");
});
Remove all sessions or individual sessions.
<td>options</td><td colspan="5"><i>object</i>
<table>
<tr><th>name</th><th>type</th><th>example</th><th>description</th><th>
argument</th><th>default</th></tr>
<tr>
<td>force</td>
<td><i>boolean</i></td>
<td><i>true</i></td>
<td>If set to true, the user will be logged out of the providers site as well as the local application. By default the user will still be signed into the providers site.</td>
<td><em>optional</em></td>
<td><i>false</i></td>
</tr>
</table>
</td></tr>
<tr><td>callback</td><td><i>function</i></td><td><code>function(){alert("Logged
in!");}</code></td><td>
A callback when the users session has been initiated</td><td>
<em>optional</em></td><td>
<em>null</em></td></tr>
name | type | example | description | argument | default |
---|---|---|---|---|---|
network | string | windows, | One of our services. | optional | null |
hello( "facebook" ).logout(function(){
alert("Signed out");
});
Get the current status of the session, this is an synchronous request and does not validate any session cookies which may have expired.
name | type | example | description | argument | default |
---|---|---|---|---|---|
network | string | windows, | One of our services. | optional | current |
var online = function(session){
var current_time = (new Date()).getTime() / 1000;
return session && session.access_token && session.expires > current_time;
};
var fb = hello( "facebook" ).getAuthResponse();
var wl = hello( "windows" ).getAuthResponse();
alert(( online(fb) ? "Signed":"Not signed") + " into FaceBook, " + ( online(wl) ? "Signed":"Not signed")+" into Windows Live");
Make calls to the API for getting and posting data
name | type | example | description | argument | default |
---|---|---|---|---|---|
path | string | /me, /me/friends | Path or URI of the resource. See REST API, Can be prefixed with the name of the service | required | null |
method | get, post, delete, put | See type | HTTP request method to use. | optional | get |
data | object | {name: |
A JSON object of data, FormData, HTMLInputElement, HTMLFormElment to be sent along with a get, postor putrequest | optional | null |
callback | function | function(json){console.log(json);} | A function to call with the body of the response returned in the first parameter as an object, else boolean false | optional | null |
hello( "facebook" ).api("me").success(function(json){
alert("Your name is "+ json.name);
}).error(function(){
alert("Whoops!");
});
Bind a callback to an event. An event maybe triggered by a change in user state or a change in some detail.
event | description |
---|---|
auth | Triggered whenever session changes |
auth.login | Triggered whenever a user logs in |
auth.logout | Triggered whenever a user logs out |
auth.update | Triggered whenever a users credentials change |
var sessionstart = function(){
alert("Session has started");
};
hello.on("auth.login",sessionstart);
Remove a callback, both event name and function must exist
hello.off("auth.login",sessionstart);
A convenient function to get the next
resultset is provided in the second parameter of any GET
callback. Calling this function recreates the request with the original parameters and event listeners. Albeit the original path is augmented with the parameters defined in the paging.next
property.
hello( "facebook" ).api( "me/friends", {limit: 1} ).success( function( json, next ){
if( next ){
if( confirm( "Got friend "+ json.data[0].name + ". Get another?" ) ){
next();
}
}
else{
alert( "Got friend "+ json.data[0].name + ". That's it!" );
}
}).error( function(){
alert("Whoops!");
});
The scope property defines which privileges an app requires from a network provider. The scope can be defined globally for a session through hello.init(object, {scope:'string'})
, or at the point of triggering the auth flow e.g. hello('network').login({scope:'string'});
An app can specify multiple scopes, seperated by commas - as in the example below.
hello( "facebook" ).login( {scope: "friends,photos,publish" } );
Scopes are tightly coupled with API requests, which will break if the session scope is missing or invalid. The best way to see this is next to the API paths in the hello.api reference table.
The table below illustrates some of the default scopes HelloJS exposes. Additional scopes may be added which are proprietary to a service, but take careful not to mix proprietary scopes with other services which dont know how to handle them.
Scope | Description |
---|---|
default | Read basic profile |
friends |
Read friends profiles |
photos |
Read users albums and photos |
files |
Read users files |
publish |
Publish status updates |
publish_files |
Publish photos and files |
Its good practice to limit the use of scopes and also to make users aware of why your app needs certain privilieges. Try to update the permissions as a user delves further into your app. For example: If the user would like to share a link with a friend; Include a button which the user has to click to trigger the hello.login with the 'friends' scope, and then the handler triggers the API call after authorisation.
For hello.api([path], [callback]) the first parameter of callback upon error will be either boolean (false) or be an error object as described below.
name | type | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
error | object
|
Services are added to HelloJS as "modules" for more information about creating your own modules and examples, go to Modules
Services which rely on the OAuth 1 authentication method require a server side handshake with the secret key - this is unlike client-side OAuth 2 which doesn't need a secret and verifies the app based on the redirect_uri property.
Making HelloJS work with OAuth1 endpoints requires a proxy server to authorize the user and sign subsequent requests. As a shim HelloJS uses a service hosted at http://auth-server.herokuapp.com/ developers may add their own network registration AppID/client_id and secret to this service in order to easily get started.
The aforementioned service uses //node-oauth-shim, so go npm install oauth-shim
that for your own deployment.
Browser | IE10 | IE9 | IE8 | IE7 | FF | CR | SA | OP | Mob | Mini5 | iOS | WP 7 |
---|---|---|---|---|---|---|---|---|---|---|---|---|
hello.js | ✓ | ✓ | ✓ | ✓1,2 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓3 | ✓ | ✓4 |
IE7: Makes beeping sounds whenever the POST, PUT or DELETE methods are used - because of the XD, IFrame+Form+hack.
- IE7: Requires JSON.js and localStorage shims
- Opera Mini: Supports inline consent only, i.e. reloads original page.
- WP7: Supports inline consent only, i.e. reloads original page.
"No, It's perfect!".... If you believe that then give it a star.
Having read this far you have already invested your time, why not contribute!?
HelloJS is constantly evolving, as are the services which it connects too. So if you think something could be said better, find something buggy or missing from either the code, documentation or demos then please put it in, no matter how trivial.
Please adopt the continuous integration tests.
# Using NodeJS on your dev environment
# cd into the project root and install dev dependencies
npm install -l
# run continuous integration tests
npm test
Open a couple of browsers with the given URL (e.g. it'll say "Karma v0.9.8 server started at http://localhost:9876/"). The tests are triggered when the code is modified