User Rating: 4.8/5 ( 2 votes)
hello.js is 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.
Features:
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 |
FaceBook |
Google |
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.
-
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.
Source: adodson.com
1. REGISTER YOUR APP DOMAIN
Register your application with atleast one of the following networks. Ensure you register the correct domain as they can be quite picky
2. INCLUDE JS FILES
<script class="pre" src="./dist/hello.all.min.js"></script>
3. HTML
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>
4. JAVASCRIPT
Add listeners for the user login
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);
});
});
Configure hello.js with your client_id's and initiate all listeners
Now let's wire it up with our registration detail obtained in step 1. By passing a [key:value, ...] list into thehello.init function. e.g....
hello.init({
facebook : FACEBOOK_CLIENT_ID,
windows : WINDOWS_CLIENT_ID,
google : GOOGLE_CLIENT_ID
},{redirect_uri:'redirect.html'});
5. METHODS
hello.init()
Initiate the environment. And add the application credentials
hello.init( {facebook: id, windows: id, google: id, .... } )
name |
type |
credentials |
object( key => value, ... )
name |
type |
example |
description |
argument |
default |
key |
string |
windows,facebook orgoogle |
App name"s |
required |
n/a |
value |
string |
0000000AB1234 |
ID of the service to connect to |
required |
n/a |
|
options |
set's default options, as in hello.login() |
Example:
hello.init({
facebook : '359288236870',
windows : '000000004403AD10'
});
hello.login()
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.
hello.login( [network] [,options] [, callback() ] )
name |
type |
example |
description |
argument |
default |
network |
string |
windows, facebook |
One of our services. |
required |
null |
options |
object
name |
type |
example |
description |
argument |
default |
display |
string |
popup,page ornone |
How the signin flow should work, "none" is used to refresh the access_token in the background |
optional |
popup |
scope |
string |
email,publish orphotos |
Comma separated list of scopes |
optional |
null |
redirect_uri |
string |
redirect.html |
A full or relative URI of a page which includes this script file hello.js |
optional |
window.location.href |
response_type |
string |
token,code |
Mechanism for skipping auth flow |
optional |
token |
force |
Boolean |
false: return current session else initiate auth flow; true: Always initiate auth flow |
Mechanism for authentication |
optional |
true |
|
callback |
function |
function(){alert("Logged in!");} |
A callback when the users session has been initiated |
optional |
null |
Examples:
hello( "facebook" ).login( function(){
alert("You are signed in to Facebook");
});
hello.logout()
Remove all sessions or individual sessions.
hello.logout( [network] [, options ] [, callback() ] )
name |
type |
example |
description |
argument |
default |
network |
string |
windows, facebook |
One of our services. |
optional |
null |
options |
object
name |
type |
example |
description |
argument |
default |
force |
boolean |
true |
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. |
optional |
false |
|
callback |
function |
function(){alert("Logged in!");} |
A callback when the users session has been initiated |
optional |
null |
Example:
hello( "facebook" ).logout(function(){
alert("Signed out");
});
hello.getAuthResponse()
Get the current status of the session, this is an synchronous request and does not validate any session cookies which may have expired.
hello.getAuthResponse( network );
name |
type |
example |
description |
argument |
default |
network |
string |
windows, facebook |
One of our services. |
optional |
current |
Examples:
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");
hello.api()
Make calls to the API for getting and posting data
hello.api( [ path ], [ method ], [ data ], [ callback(json) ] )
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:Hello, description:Fandelicious} |
A JSON object of data, FormData, HTMLInputElement, HTMLFormElment to be sent along with aget, postorputrequest |
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 |
Examples:
hello( "facebook" ).api("me").success(function(json){
alert("Your name is "+ json.name);
}).error(function(){
alert("Whoops!");
});
6. EVENTS
hello.on()
Bind a callback to an event. An event maybe triggered by a change in user state or a change in some detail.
hello.on( event, callback );
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 |
Example:
var sessionstart = function(){
alert("Session has started");
};
hello.on("auth.login",sessionstart);
hello.off()
Remove a callback, both event name and function must exist
hello.off( event, callback );
hello.off("auth.login",sessionstart);