Professional Documents
Culture Documents
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. If you don't
have hosting, you can get set up quickly with Parse.
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.
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.
6. Log out.
The response object that's provided to your callback contains a number of fields:
{
status: 'connected',
authResponse: {
accessToken: '...',
expiresIn:'...',
signedRequest:'...',
userID:'...'
}
specifies the login status of the person using the app. The status can be one of the
following:
status
o connected. The person is logged into Facebook, and has logged into your app.
o not_authorized. The person is logged into Facebook, but has not logged into
your app.
o unknown. The person is not logged into Facebook, so you don't know if they've
logged into your app.
authResponse
o accessToken. Contains an access token for the person using the app.
o expiresIn. Indicates the UNIX time when the token expires and needs to be
renewed.
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.
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:
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);
});
}
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'});
Permissions are covered in depth in our permissions guide. However, there are a few things to
remember when dealing with permissions and the login dialog:
You ask for permissions when the dialog is created. The resulting set of permissions is
tied to the access token that's returned.
Other platforms may have a different set of permissions. For example, on iOS you can
ask for places a person's been tagged, while in the web version of your app that
permission is not required for the experience.
You can add permissions later when you need more capabilities. When you need a new
permission, you simply add the permission you need to the list you've already granted, relaunch the Login Dialog and it will ask for the new permission.
The Login Dialog lets people decline to share certain permissions with your app that
you ask for. Your app should handle this case. Learn more about this in our permissions
dialog.
Apps that ask for more than public_profile, email and user_friends must be
reviewed by Facebook before they can be made available to the general public.
Learn more in our documentation for login review and our general review guidelines.
making calls from a server, you will need to generate a long lived token, which is covered at
length in our access token documentation.
Verifying identity
Apps normally need to confirm that the response from the Login dialog was made from the same
person who started it. If you're using Facebook's JavaScript SDK it automatically performs these
checks so nothing is required, assuming that you're only making calls from the browser.
If you decide to send it back to the server, you should make sure you re-verify the access token
once it gets to the server. Re-verifying the token is covered in our documentation on manually
building login flows. You'll need to verify that the app_id and user_id match what you
expected from the access token debug endpoint.
If you're making calls server side with the access token, you can use an SDK on the server to
make similar calls. Many people use PHP to build web applications. You can find some examples
of making server-side API calls in our PHP SDK documentation.
Note: This function call will also log the person out of Facebook. The reason for this is that
someone may have logged into your app and into Facebook during the login flow. If this is the
case, they might not expect to still be logged into Facebook when they log out of your app. To
avoid confusing people and to protect personal security, we enforce this logout behavior.
Additionally, logging out is not the same as revoking login permission (removing previously
granted authentication), which can be performed separately. Because of this your app should be
built in such a way that it doesn't automatically force people who have logged out back to the
Login dialog.
Adding Permissions
One of the best practices with Facebook Login is to not request read permissions and publishing
permissions at the same time. To support this your app can ask for more permissions later, well
after someone has logged in. To do that, all you have to do is launch the Login Dialog with the
new permission that you're asking for.
For example, let's say you had a Login Button with the following permissions:
<fb:login-button scope="public_profile,email" onlogin="checkLoginState();">
</fb:login-button>
And if you checked /me/permissions for permissions granted after the person accepted you
would find this:
{"data":
[
{
"permission":"public_profile",
"status":"granted"
},
{
"permission":"email",
"status":"granted"
}
]
}
If you wanted to add the user_friends permission later, you could re-launch it with the
FB.login() function like this:
FB.login(function(response) {
console.log(response);
}, {scope: 'user_friends'});
(This function must be called from a button's event handler otherwise it's likely to be blocked by
browser popup blockers.)
The dialog that it generates looks like this:
Note that it only asks for the new permission. If you accept the new permission checking
/me/permissions will result in this:
{"data":
[
{
"permission":"public_profile",
"status":"granted"
},
{
"permission":"email",
"status":"granted"
},
{
"permission":"user_friends",
"status":"granted"
}
Note that the new user_friends permission has been added to the list of allowed permissions.
The public_profile permission is always required and greyed out because it can't be disabled.
However, if someone were to uncheck user_likes (Likes) in this example, checking
/me/permissions for what permissions have been granted results in:
{
"data":
[
{
"permission":"public_profile",
"status":"granted"
},
{
"permission":"user_likes",
"status":"declined"
]
When you do that, the Login Dialog will re-ask for the declined permission. The dialog will look
very much like the dialog in the section on re-asking for permissions but will let you re-ask for a
declined permission.
Additional Resources
Login Dialog
Facebook SDK for JavaScript Reference for FB.login()
Login Button
A simple way to trigger the Login Dialog.