Welcome to Geni's JavaScript SDK

The Geni Javascript SDK is a full featured javascript library allowing developers to build dynamic web applications in the browser with Geni's data. It enables full access to all of Geni's API methods on the client-side and provides robust functionality for working with Oauth 2.0 authentication.

JavaScript SDK Source Code

http://geni.com/jsdk.js

Getting Started

To get started, you'll need to add the library to your page, and initialize your app by calling Geni.init(), passing in your application key. The best place to put this is at the bottom of your page, before the closing </body> tag to prohibit blocking parallel downloads as described in Yahoo's best practices.

<script src="http://geni.com/jsdk.js"></script>
<script>
  Geni.init({
    app_id: 'YOUR_APP_KEY'
  });
</script>

In addition to app_id, Geni.init() has a few optional parameters.

<script src="http://geni.com/jsdk.js"></script>
<script>
  Geni.init({
    app_id: 'YOUR_APP_KEY',
    host: 'http://sandbox.geni.com',    // change host if needed
    cookie: true,                       // enables saving the access token to a cookie on the users machine
    logging:true                        // enable log messages to help in debugging
  });
</script>

Authentication

Once your app has been initialized you can authenticate the user. Geni uses Oauth 2.0 for authentication, which entails getting an access token for a user via a redirect to the Geni.com website. Once a user approves your application you can then use the access token to make authorized requests to Geni's API on behalf of that user.

Geni.getStatus

To authenticate a user via the Javascript SDK you'll need to figure out whether the user is logged in and whether that user has already authorized your application. To do this we can use Geni.getStatus().

Geni.getStatus(function(response) {
  if (response.status == 'authorized') {
    // User is logged in and has authorized your application.
    // You can now make authorized calls to the API.
  } else {
    // User is either logged out, has not authorized the app or both.
  }
});

The Geni.getStatus() method will make a request to Geni to obtain the current status of the user. The request will respond with one of three status types:

"authorized" - the user is logged in to Geni and has authorized your application "unauthorized" - the user is logged in to Geni but has not authorized your application "unknown" - the user is logged out of Geni

Geni.connect

If the status is 'authorized', an access token will be returned which can then be used to start making API calls. If the status is either 'unauthorized' or 'unknown', your application will need to prompt the user to login and/or authorize by calling Geni.connect().

Geni.connect(function(response) {
  if(response.status == 'authorized') {
    // User is logged in and has authorized your application.
    // You can now make authorized calls to the API.
  } else {
    // User canceled the popup
  }
});

Geni.connect() will open a small popup window to the Geni.com site, prompting the user to login and authorize your application. The popup will close immediately after authorization is either allowed or disallowed.

Just like the Geni.getStatus() method, Geni.connect() returns user status and an access token if the user authorizes the application. Note: Because calling this method opens a popup window to the Geni.com site, it should only be called on a user action like a click on a button or link, as most browsers will block the popup unless they are the result of a user initiated event.

Geni.logout

At some point you may wish to offer your users a way to logout of Geni. To do this the Javascript SDK offers the logout() method.

Geni.logout(function() {
  // The user is now logged out of Geni
  // Your application will no longer be able to make api calls on the users behalf until they log back in
});

Status Change Events

The Javascript SDK also provides an 'auth:statusChange' event that can be subscribed to. The event fires when the user's status changes as the result of calling one of these methods.

Geni.Event.bind('auth:statusChange',function(status) {
  // status will be either 'authorized', 'unauthorized' or 'unknown'
});

Similar to jQuery, you can subscribe/unsubscribe from events using bind (Geni.Event.bind) and unbind (Geni.Event.unbind).

Making API Calls

Once you have an authenticated user, you are free to make calls to the Geni API. With the Javascript SDK, developers get full access to the API directly through the user's browser via the Geni.api() method.

The first argument is the path to the API method and it is the only required argument. IDs are embedded before the action so the urls read more like a sentence. For instance, to get all profile 101’s tree matches you would request:

Geni.api('/profile-101/tree_matches', function(response) {
  // returns a list of tree matches for profile with id 101
});

Omitting the ids in urls implies the action should be applied to the current user’s data.

Geni.api('/profile', function(response) {
  // returns current user's profile data
  // alert(response.name)
});

Specific parameters can optionally be passed in as the second argument.

Geni.api('/profile', { fields : 'first_name'}, function(data)
  // only returns first name of profile current users profile
  alert("Welcome + " " + response.first_name);
});

For post requests, you'll need to pass a 'method' parameter in the second argument.

Geni.api('/profile', {
    method:'post',
    first_name: 'John'
  }, function(response) {
    // the current users first name is now set to 'John'
});

LICENSE

This library is licensed under the MIT license which can be found in the LICENSE file in the same directory as this README file.