Login Status

FB.getLoginStatus() allows you to determine if a user is logged in to Facebook and has authenticated your app. There are three possible states for a user:

1. the user is logged into Facebook and has authenticated your application (connected)
2. the user is logged into Facebook but has not authenticated your application (not_authorized)
3. the user is either not logged into Facebook or explicitly logged out of your application so it doesn't attempt to connect to Facebook and thus, we don't know if they've authenticated your application or not (unknown)

Knowing which of the these three states the user is in is one of the first things your application needs to know on page load.

Example

To determine if a user has authenticated your app:

FB.getLoginStatus(function(response) {
  if (response.status === 'connected') {
    // the user is logged in and has authenticated your
    // app, and response.authResponse supplies
    // the user's ID, a valid access token, a signed
    // request, and the time the access token 
    // and signed request each expire
    var uid = response.authResponse.userID;
    var accessToken = response.authResponse.accessToken;
  } else if (response.status === 'not_authorized') {
    // the user is logged in to Facebook, 
    // but has not authenticated your app
  } else {
    // the user isn't logged in to Facebook.
  }
 });

Response objects

If the user has authenticated your application, the response object will look like this:

{
    status: 'connected',
    authResponse: {
        accessToken: '...',
        expiresIn:'...',
        signedRequest:'...',
        userID:'...'
    }
}

In some cases, you will get an authResponse but your app is not authorized to make further calls. This can happen if the app was removed from the settings but the webpage using the JS SDK wasn't refreshed. So you should also check the response status message for this issue.

If the authResponse object is not present, the user is either not logged into Facebook, or has not authorized your app.

The most useful parts of the authResponse object are the userID (the user's ID) and the accessToken. The access token can be used to make requests to the Facebook APIs on behalf of that user. The userID is the unique identifier for the user who's present in your app.

Roundtrips to Facebook's servers

To improve the performance of your application, not every call to check the status of the user will result in request to Facebook's servers. Where possible, the response is cached. The first time in the current browser session that FB.getLoginStatus is called, or the JS SDK is init'd with status: true, the response object will be cached by the SDK. Subsequent calls to FB.getLoginStatus will return data from this cached response.

This can cause problems where the user has logged into (or out of) Facebook since the last full session lookup, or if the user has removed your application in their account settings.

To get around this, you call FB.getLoginStatus with the second parameter set to true to force a roundtrip to Facebook - effectively refreshing the cache of the response object.

FB.getLoginStatus(function(response) {
  // this will be called when the roundtrip to Facebook has completed
}, true);

If you call FB.getLoginStatus on every page load, be careful not to set this parameter for each as it will significantly increase the number of requests to Facebook's servers, and thus decrease the performace of your application.

Checking user status on page load

While you can call FB.getLoginStatus any time (for example, when the user tries to take a social action), most social apps need to know the user's status as soon as possible after the page loads. In this case, rather than calling FB.getLoginStatus explicitly, it is possible to check the user's status by setting status: true when you call FB.init.

To receive the response of this call, you must subscribe to the auth.statusChange event. The response object passed by this event is identical to that which would be returned by calling FB.getLoginStatus explicitly.

Login Status Events

Subscribing to the authentication events fired by the JS SDK means your app will be notified if the user's session state changes. This is important because the session state may change due to user interactions beyond your app's control. The only way your app can be notified of these changes is through subscribing to these event.

Examples of interactions which can change the state of the user include FB.login(), FB.logout() and the Login button. Widgets such as the Comments plugin may also trigger authentication.

auth.login

This event is fired when your app first notices the user (in other words, gets a session when it didn't already have a valid one).

auth.logout

This event is fired when your app notices that there is no longer a valid user (in other words, it had a session but can no longer validate the current user).

auth.authResponseChange

This event is fired for any auth related change as they all affect the session: login, logout, session refresh. Sessions are refreshed over time as long as the user is active with your app.

auth.statusChange

Typically you will want to use the auth.authResponseChange event. But in rare cases, you want to distinguish between these three states:

• Connected
• Logged into Facebook but not connected with your application
• Not logged into Facebook at all.

The FB.Event.subscribe and FB.Event.unsubscribe functions are used to subscribe to these events. For example:

FB.Event.subscribe('auth.login', function(response) {
  // do something with response
});

The response object returned to all these events is the same as the response from FB.getLoginStatus, FB.login or FB.logout. This response object contains:

status

The status of the User. One of connected, not_authorized or unknown.

authResponse

The authResponse object.

Configuration

In order to use the authentication methods, your app must be configured with an App Domain. App settings can be changed on the settings page.

Related Documentation

• Improve user experience with automatic login