hello.js

A client-side JavaScript SDK for authenticating with OAuth2 (and OAuth1 with a oauth proxy) web services and querying their REST APIs. HelloJS standardizes paths and responses to common APIs like Google Data Services, Facebook Graph and Windows Live Connect. It's modular, so that list is growing. No more spaghetti code!

E.g.

See demo at https://adodson.com/hello.js/.

Features

Here are some more demos...

	Windows	Facebook	Google	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 a work in progress, but there is good evidence that they can be done.
• I have no knowledge of anything unlisted and would appreciate input.

Install

Download: HelloJS | HelloJS (minified)

Compiled source, which combines all of the modules, can be obtained from GitHub, and source files can be found in Source.

Note: Some services require OAuth1 or server-side OAuth2 authorization. In such cases, HelloJS communicates with an OAuth Proxy.

NPM

npm i hellojs

At the present time only the bundled files in the /dist/hello.* support CommonJS. e.g. let hello = require('hellojs/dist/hello.all.js').

Bower

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.

Help & Support

• GitHub for reporting bugs and feature requests.
• Gitter to reach out for help.
• Stack Overflow use tag hello.js
• Slides by Freddy Harris

Quick Start

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 sign-in buttons
• Setup listener for login and retrieve user info
• Initiate the client_ids and all listeners

1. Register

Register your application with at least one of the following networks. Ensure you register the correct domain as they can be quite picky.

• Facebook
• Windows Live
• Google+

2. Include Hello.js script in your page

<script src="https://github.com/MrSwitch/hello.js/raw/v2.0.0-4/dist/hello.all.js"></script>

3. Create the sign-in buttons

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. Add listeners for the user login

Let's define a simple function, which will load a user profile into the page after they sign in 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').then(function(r) {
        // Inject it into the container
        var label = document.getElementById('profile_' + auth.network);
        if (!label) {
            label = document.createElement('div');
            label.id = 'profile_' + auth.network;
            document.getElementById('profile').appendChild(label);
        }
        label.innerHTML = '<img src="https://github.com/MrSwitch/hello.js/raw/v2.0.0-4/' + r.thumbnail + '" /> Hey ' + r.name;
    });
});

5. Configure hello.js with your client IDs 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 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.

Core 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 or google App names required n/a value string 0000000AB1234 ID of the service to connect to required n/a
options	sets 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 or none "popup" - as the name suggests, "page" - navigates the whole page, "none" - refresh the access_token in the background optional popup scope string email, publish or photos Comma separated list of scopes optional null redirect_uri string Redirect Page A full or relative URI of a page which includes this script file hello.js optional window.location.href response_type string token, code Implicit (token) or Explicit (code) Grant flow optional token force Boolean or null true, false or null (true) initiate auth flow and prompt for reauthentication where available. (null) initiate auth flow. (false) only prompt auth flow if the scopes have changed or the token expired. optional null popup object {resizable:1} Overrides the popups specs optional See hello.settings.popup state string ijustsetthis Honours the state parameter, by storing it withing its own state object optional
callback	function	function(){alert("Logged in!");}	A callback when the users session has been initiated	optional	null

Examples:

hello('facebook').login().then(function() {
    alert('You are signed in to Facebook');
}, function(e) {
    alert('Signin error: ' + e.error.message);
});

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 out!');}	A callback when the users session has been terminated	optional	null

Example:

hello('facebook').logout().then(function() {
    alert('Signed out');
}, function(e) {
    alert('Signed out error: ' + e.error.message);
});

hello.getAuthResponse()

Get the current status of the session. This is a 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:

```js var online = function(session) { var currentTime = (new Date()).getTime() / 1000; retur