Detecting Connect Status
From Facebook Developer Wiki
Contents |
[edit] Detecting whether users are logged in to Facebook and/or your site
This article covers how to detect whether a user is logged in to Facebook when they visit your site, and whether they are already a connected user of your site.
[edit] Benefits
With some simple Javascript, you can immediately detect when a logged in Facebook user is visiting your site. More importantly, if the user has already connected with your site, you can log them in automatically whenever they are logged in to Facebook. We call this "single sign on", where a user is automatically logged in to sites they have connected with, and when they log out of Facebook, they are logged out of all of them.
When you enable single sign-on, your users will maintain a persistent Facebook session across multiple domains. This will allow you to potentially increase engagement through a low friction login and detection process.
Detecting a user’s Connect status has many significant benefits.
- The ability to automatically login a Connected user when they return to your website.
- The ability to automatically prompt a user to Connect.
- The ability to store metrics of Facebook users.
- The number of logged in Facebook users who visit your site.
- The number of users who have Connected with your site.
- The number of users who Connect to your site when already logged in to Facebook versus those who have not logged in*.
Over 40% of Facebook users are logged in using third party sites.
[edit] How It Works
When a user visits your site and has already logged in to Facebook or a Facebook Connect enabled site, you can perform a number of actions that enhance the user’s experience.
[edit] Scenario 1: Detect a User From Computer to Computer
The user visits your site and connects with Facebook from his or her computer. When the user logs in to Facebook and returns to your site using another computer, the user will be automatically logged in to your site.
[edit] Scenario 2: Detect Users Coming Directly From Facebook
A user publishes a story from your site to his or her stream.
A friend of that user sees the story and clicks on the link, taking them to your site.
After the friend arrives at your site, you detect that he or she is logged into Facebook, and you immediately present a dialog to Connect.
[edit] Implementation
The implementation of this feature requires using Javascript to first detect the logged in state of the Facebook user. This must be done via Javascript after your page loads because this must ping Facebook's servers via Javascript using the Facebook cookies. Once the Javascript detection first happens, you can reload a page or use Ajax to update your page automatically.
Many developers have asked how to detect this automatically on the server when a user first appears on their site. This is not possible unless the user has granted an infinite session. If you were familiar with building a Facebook Application on Facebook, it did work this way, but that was because the app was running within Facebook.
This implementation relies on the understanding of three states of Facebook Connect. You can determine the current state for a user visiting your site via the JavaScript method FB.Connect.get_status.
- Connected – the user is logged in to Facebook and has already connected with your website. You must be in this state to make API calls on the user's behalf. This state is returned as FB.ConnectState.connected if you call FB.Connect.get_status.
- Not logged in – this state means that the user is not logged in to Facebook. Because the user is not logged in to Facebook, we don't know whether the user has connected with your website. In order to make API calls on the user's behalf, you must first have the user log in (and potentially connect) with your site. This state is returned as ConnectState.userNotLoggedIn if you call FB.Connect.get_status.
- Not authorized – this state means that the user is logged in to Facebook but has not yet connected with your website. In order to make API calls on the user's behalf, you must first have the user connect with your site. This state is returned as ConnectState.appNotAuthorized if you call FB.Connect.get_status.
For most applications, the distinction between (2) and (3) is not important (that is, they are both a "not connected" state). Though if you are storing information in your own cookies, you may want to remember which users have connected their accounts, and if they are in state 2 (not logged in), then you may still want to prompt them more actively to log in.
There a number of scenarios that may arise when you try to determine a user’s Connect state.
- Basic FB.init() usage and calling (default)
- Reloading Page on Connect State Changes
- Requiring a Specific Connect state
- Handling Connect State Changes Dynamically
[edit] 1. Basic FB.init() usage and calling (default)
To get the user’s current connect state, you first need to initialize Facebook Connect by calling FB.Connect.init. Once initialized, you can call FB.Connect.get_status to determine the user’s state.
[edit] 2. Reloading Page on Connect State Changes
For sites whose content is partially or fully generated on the server-side, it's often simplest to reload the page when the user either connects or logs out.
To enable this scenario, you can pass a configuration setting "reloadIfSessionStateChanged":true to the FB.Connect.init function. For example:
[edit] 3. Requiring a Specific Connect state
Some sites use separate pages for connected and non-connected users. For example, a website may choose to use index.php to serve a user who has not yet logged in/connected, and use member.php to serve users who are logged in/connected. To enable this scenario, you can use the ifUserConnected and ifUserNotConnected settings.
On index.php, you can call:
By setting "ifUserConnected":"member.php", this Web page will automatically redirect to member.php when it detects that the current user is already connected.
On member.php, you can call:
By setting "ifUserNotConnected":"index.php", this Web page will automatically redirect to index.php when it detects that the current user is not connected.
[edit] 4. Handling Connect State Changes Dynamically
Some sites rely on client-side techniques (JavaScript, AJAX requests, etc.) to respond to state changes without a page reload. To handle this situation, you can also specify a callback function for ifUserConnected and ifUserNotConnected:
With this setting, the onConnected function will be invoked whenever the user is connected and the onNotConnected function will be invoked whenever the user is logged out.
[edit] Best Practices
Being able to detect the current Connect state of a user is a powerful tool.
Even if you aren't supporting a deep integration with Facebook Connect, you can use this javascript to tweak the presentation of your site for Facebook-related features, and make them much more prominent when a logged-in Facebook user is visiting your site.
- For example, if you support a Share button as part of a list of several sharing options, when you detect a Facebook user, you can make the Facebook Share button most prominent.
- If you are using Facebook Connect as a way to log in to your site, you can use the detection methods listed here to immediately log the user in whenever they are logged into Facebook and visit your site. This would work even if they visit a new computer and log into Facebook first.
A few more notes:
- Based on some of our analysis, over 40% of users visiting other websites are actively logged in to Facebook.
- When users click on links from Facebook to your site (such as an advertisement on Facebook, or a link or story shared by a friend of theirs), they will be logged into Facebook. Using these detection methods for links that come from Facebook is a great way to increase your conversion rate and the success of the social loop.
[edit] Reference
- public static void FB.init (string apiKey, string xdChannelUrl, object appSettings)
- public static void FB.init (object appSettings)
- public static void FB.Facebook.init (string apiKey, string xdChannelUrl, object appSettings)
- public static void FB.Facebook.init (object appSettings)
[edit] Advanced Use
If the simple configuration settings are not are sufficient for your scenario, you can also use other API calls to track user state.
- public static void FB.Connect.ifUserConnected (object connectedArg, object notConnectedArg)
- public static Waitable FB.Connect.get_status()
- public static Waitable FB.Facebook.get_sessionWaitable()
Note: While these approaches are asynchronous, the actual execution will often be synchronous due to client-side caching of server state.
If you are not using Facebook as your primary login mechanism, you can still use the user's Connect status to automatically log users into your site using your own account system. To do this, simply store a mapping from Facebook user IDs to your own account identifiers and then use the Facebook session to look up and use a local account on your site. See Account Linking for more details.
