Facebook Login for the Web with the JavaScript SDK

Facebook apps can use one of several login flows, depending on the target device and the project. This guide takes you step-by-step through the login flow for web apps. The steps in this guide use the Facebook SDK for JavaScript , which is the recommended method to add Facebook Login to your website.

If for some reason you can't use our JavaScript SDK you can also implement login without it. We've build a separate guide to follow if you need to implement login manually.

Quickstart

Later in this doc we will guide you through the login flow step-by-step and explain each step clearly - this will help you if you are trying to integrate Facebook Login into an existing login system, or just to integrate it with any server-side code you're running. But before we do that, it's worth showing how little code is required to implement login in a web application using the JavaScript SDK.

You will need a Facebook App ID before you start using the SDK, which you can create and retrieve on the App Dashboard. You'll also need somewhere to host HTML files.

Full Code Example

This code will load and initialize the JavaScript SDK in your HTML page. Use your app ID where indicated.

<!DOCTYPE html>
<html>
<head>
<title>Facebook Login JavaScript Example</title>
<meta charset="UTF-8">
</head>
<body>
<script>
  // This is called with the results from from FB.getLoginStatus().
  function statusChangeCallback(response) {
    console.log('statusChangeCallback');
    console.log(response);
    // The response object is returned with a status field that lets the
    // app know the current login status of the person.
    // Full docs on the response object can be found in the documentation
    // for FB.getLoginStatus().
    if (response.status === 'connected') {
      // Logged into your app and Facebook.
      testAPI();
    } else if (response.status === 'not_authorized') {
      // The person is logged into Facebook, but not your app.
      document.getElementById('status').innerHTML = 'Please log ' +
        'into this app.';
    } else {
      // The person is not logged into Facebook, so we're not sure if
      // they are logged into this app or not.
      document.getElementById('status').innerHTML = 'Please log ' +
        'into Facebook.';
    }
  }

  // This function is called when someone finishes with the Login
  // Button.  See the onlogin handler attached to it in the sample
  // code below.
  function checkLoginState() {
    FB.getLoginStatus(function(response) {
      statusChangeCallback(response);
    });
  }

  window.fbAsyncInit = function() {
  FB.init({
    appId      : '{your-app-id}',
    cookie     : true,  // enable cookies to allow the server to access 
                        // the session
    xfbml      : true,  // parse social plugins on this page
    version    : 'v2.8' // use graph api version 2.8
  });

  // Now that we've initialized the JavaScript SDK, we call 
  // FB.getLoginStatus().  This function gets the state of the
  // person visiting this page and can return one of three states to
  // the callback you provide.  They can be:
  //
  // 1. Logged into your app ('connected')
  // 2. Logged into Facebook, but not your app ('not_authorized')
  // 3. Not logged into Facebook and can't tell if they are logged into
  //    your app or not.
  //
  // These three cases are handled in the callback function.

  FB.getLoginStatus(function(response) {
    statusChangeCallback(response);
  });

  };

  // Load the SDK asynchronously
  (function(d, s, id) {
    var js, fjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) return;
    js = d.createElement(s); js.id = id;
    js.src = "//connect.facebook.net/en_US/sdk.js";
    fjs.parentNode.insertBefore(js, fjs);
  }(document, 'script', 'facebook-jssdk'));

  // Here we run a very simple test of the Graph API after login is
  // successful.  See statusChangeCallback() for when this call is made.
  function testAPI() {
    console.log('Welcome!  Fetching your information.... ');
    FB.api('/me', function(response) {
      console.log('Successful login for: ' + response.name);
      document.getElementById('status').innerHTML =
        'Thanks for logging in, ' + response.name + '!';
    });
  }
</script>

<!--
  Below we include the Login Button social plugin. This button uses
  the JavaScript SDK to present a graphical Login button that triggers
  the FB.login() function when clicked.
-->

<fb:login-button scope="public_profile,email" onlogin="checkLoginState();">
</fb:login-button>

<div id="status">
</div>

</body>
</html>

Now you can test your app by going to the URL where you uploaded this HTML. Open your JavaScript console, and you'll see the testAPI() function display a message with your name in the console log.

Congratulations, at this stage you've actually built a really basic page with Facebook Login. You can use this as the starting point for your own app, but it will be useful to read on and understand what is happening in the code above.

Steps for Using Facebook Login With the JavaScript SDK

There are a few steps that you will need to follow to integrate Facebook Login into your web application, most of which are included in the quickstart example at the top of this page. At a high level those are:

  1. Checking the login status to see if someone's already logged into your app. During this step, you also should check to see if someone has previously logged into your app, but is not currently logged in.
  2. If they are not logged in, invoke the login dialog and ask for a set of data permissions.
  3. Verify their identity.
  4. Store the resulting access token.
  5. Make API calls.
  6. Log out.

1. Checking Login Status

The first step when loading your web page is figuring out if a person is already logged into your app with Facebook login. You start that process with a call to FB.getLoginStatus. That function will trigger a call to Facebook to get the login status and call your callback function with the results.

Taken from the sample code above, here's some of the code that's run during page load to check a person's login status:

FB.getLoginStatus(function(response) {
    statusChangeCallback(response);
});

The response object that's provided to your callback contains a number of fields:

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

status specifies the login status of the person using the app. The status can be one of the following:

  • connected. The person is logged into Facebook, and has logged into your app.
  • not_authorized. The person is logged into Facebook, but has not logged into your app.
  • unknown. The person is not logged into Facebook, so you don't know if they've logged into your app. Or FB.logout() was called before and therefore, it cannot connect to Facebook.
  • authResponse is included if the status is connected and is made up of the following:
  • accessToken. Contains an access token for the person using the app.
  • expiresIn. Indicates the UNIX time when the token expires and needs to be renewed.
  • signedRequest. A signed parameter that contains information about the person using the app.
  • userID is the ID of the person using the app.

Once your app knows the login status of the person using it, it can do one of the following:

  • If the person is logged into Facebook and your app, redirect them to your app's logged in experience.
  • If the person isn't logged into your app, or isn't logged into Facebook, prompt them with the Login dialog with FB.login() or show them the Login Button.

2. Logging People In

If people using your app aren't logged into your app or not logged into Facebook, you can use the Login dialog to prompt them to do both. Various versions of the dialog are shown below.

If they aren't logged into Facebook, they'll first be prompted to log in and then move on to logging in to your app. The JavaScript SDK automatically detects this, so you don't need to do anything extra to enable this behavior.

There are two ways to log someone in:

  • Use the Login Button.
  • Use FB.login() from the JavaScript SDK.

3. Using the Login Button

Including the Login Button into your page is easy. Visit the documentation for the login button and set the button up the way you want. Then click Get Code and it will show you the code you need to display the button on your page.

Note that in the example at the start of this document, we use the onlogin attribute on the button to set up a JavaScript callback that checks the login status to see if the person logged in successfully:

<fb:login-button scope="public_profile,email" onlogin="checkLoginState();">
</fb:login-button>

This is the callback. It calls FB.getLoginStatus() to get the most recent login state. (statusChangeCallback() is a function that's part of the example that processes the response.)

function checkLoginState() {
  FB.getLoginStatus(function(response) {
    statusChangeCallback(response);
  });
}

4. Invoking the Login Dialog with the JavaScript SDK

For apps that want to use their own button, you can invoke the Login Dialog with a simple call to FB.login():

FB.login(function(response){
  // Handle the response object, like in statusChangeCallback() in our demo
  // code.
});

As noted in the reference docs for this function, it results in a popup window showing the Login dialog, and therefore should only be invoked as a result of someone clicking an HTML button (so that the popup isn't blocked by browsers).

There is an optional scope parameter that can be passed along with the function call that is a comma separated list of permissions to request from the person using the app. Here's how you would call FB.login() with the same scope as the Login Button we used above. In this case, it would ask for a person's email address and a list of friends who also use the app:

 FB.login(function(response) {
   // handle the response
 }, {scope: 'public_profile,email'});

5. Handling Login Dialog Response

At this point in the login flow, your app displays the Login dialog, which gives people the choice of whether to cancel or to enable the app to access their data.

Whatever choice people make, the browser returns to the app and response data indicating whether they're connected or cancelled is sent to your app. When your app uses the JavaScript SDK, it returns an authResponse object to the callback specified when you made the FB.login() call:

This response can be detected and handled within the FB.login call, like this:

FB.login(function(response) {
  if (response.status === 'connected') {
    // Logged into your app and Facebook.
  } else if (response.status === 'not_authorized') {
    // The person is logged into Facebook, but not your app.
  } else {
    // The person is not logged into Facebook, so we're not sure if
    // they are logged into this app or not.
  }
});

Additional Resources

Login Dialog

Facebook SDK for JavaScript Reference for FB.login()

Login Button

A simple way to trigger the Login Dialog.