What Is WP-FB AutoConnect?


The simple concept behind WP-FB AutoConnect is to offer an easy-to-use widget that lets readers login to your blog with either their Facebook account or local Wordpress credentials. Although many "Facebook Connect" plugins do exist, most of them are either overly complex and difficult to customize, or fail to provide a seamless experience for new visitors. I wrote this plugin to provide what the others didn't:
  • Full support for Wordpress, Buddypress, Mingle (free addon), and MultiSite (paid addon).
  • No user interaction is required - the login process is transparent to new and returning users alike.
  • Existing users who connect with FB retain the same local user accounts as before.
  • New visitors will be given new user accounts, which can be retained even if you remove the plugin.
  • Facebook profile pictures can be used as avatars, even on pre-existing comments.
  • User registration announcements can be pushed to Facebook walls.
  • No contact with the Facebook API after the login completes - so no slow pageloads.
  • Won't bloat your database with duplicate user accounts, extra fields, or unnecessary complications.
  • Custom logging options can notify you whenever someone connects with Facebook.
  • A powerful set of hooks and filters allow developers to easily tailor the login process to their personal needs: redirect to a custom page, fill xProfile data with information from Facebook, setup permissions based on social connections, and more.
  • Fully HTML/CSS valid.

WP-FB AutoConnect Premium


To address the needs of more advanced users, I've created an additional Premium add-on which extends the functionality of the free WP-FB AutoConnect plugin. This add-on currently provides the following:

Premium Features:
  • MultiSite Support (Mouseover for more information)
  • Cache Facebook avatars (Mouseover for more information)
  • Require access to user's real email (Mouseover for more information)
  • Auto-fill BuddyPress X-Profile fields with information from Facebook (new!)
  • Show an AJAX spinner to indicate load-in-progress after clicking the Login button
  • Customize the login button's size and text (handy for localizing to another language)
  • Add a Facebook button to the comment form, login form, WP registration form, and WPMU signup form
  • Customize the Redirect URL for first-time visitors ("Welcome" page), returning visitors ("Welcome Back" page), and logged-out visitors ("Come back soon" page)
  • Restrict autoregistration to Facebook friends, Facebook fans, Facebook group members, explicitly invited users (via Secure Invites), everyone, or no one
  • Send a customizable welcome mail to autoregistered users (with their generated login and password)
  • Silently handle "double-logins" (Mouseover for more information)
  • Show links to connected users' Facebook profiles in the "Users" admin page
In addition, the add-on includes a Premium Widget that enables you to:
  • Customize all visible text (Mouseover for more information)
  • Show a 'Remember Me' tickbox
  • Show the user's avatar (when logged in)
  • Hide the WP login fields (leaving Facebook as the only way to login)
  • Simultaneously logout of Facebook and the local blog
The add-on can be purchased for instant download by Credit Card or Paypal from the buttons below.
Important: Before making a purchase, please be sure to install and test the free plugin to confirm that it works for you; if the free version works, so will the premium:

Buy WP-FB-AutoConnect Premium (Single-Site License) - $29.99 Buy WP-FB-AutoConnect Premium (Developer License) - $69.99

Upon completing payment, you can grab the file by visiting Account -> Downloads. To install it, first setup the free version of WP-FB AutoConnect and then simply drop the purchased "WP-FB-AutoConnect-Premium.php" script into your plugins directory. This will automatically enable the premium features in your admin panel, and you may continue to update the core plugin as usual.

Suggestions for additional features may be submitted/sponsored/voted for on this project's Fundry page.

Screenshots

Here are some screenshots of the plugin; click each one for a larger view and description:
Screenshot Screenshot Screenshot Screenshot Screenshot Screenshot Screenshot Screenshot Screenshot Screenshot

Instructions


To allow your users to login with their Facebook accounts, you must first setup an Application for your site:
  1. Visit www.facebook.com/developers/createapp.php
  2. Type in a name (i.e. the name of your blog). This is what Facebook will show on the login popup.
  3. Click the "Web Site" tab and fill in your "Site URL" (with a trailing slash). Note: http://example.com/ and http://www.example.com/ are not the same.
  4. Click "Save Changes," and note the API Key and Application Secret (you'll need them in a minute).
Then you can install the plugin:
  1. Download the latest version from here, unzip it, and upload the extracted files to your plugins directory.
  2. Login to your Wordpress admin panel and activate the plugin.
  3. Navigate to Settings -> WP-FB AutoConn.
  4. Enter your Application's API Key and Secret (obtained above), and click "Save."
  5. If you're using BuddyPress, a Facebook button will automatically be added to its built-in login panel. If not, navigate to Appearance -> Widgets and add the WP-FB AutoConnect widget to your sidebar.
That's it - users should now be able to login to your blog with their Facebook accounts.

Customizing


How it Works

Before getting into any advanced customization, you should have a general understanding of how the login process works. When a user clicks the login button, a Facebook form pops up, they fill in their info, it closes, and a javascript callback function redirects them to _process_login.php. This is the heart of the plugin. Here's what it does:
  1. Access the User's Facebook account and get their uid (userID)
  2. Search for existing WP users tagged with this visitor's Facebook uid; whenever someone successfully connects, the plugin tags them with usermeta so it can quickly match them to their WP user account on subsequent logins. If found, this is the existing WP user we'll login.
  3. If nobody is found via usermeta, we search all existing users for someone with the same email address as the connecting FB member (assuming you've opted to ask them for their email). If found, this is the existing WP user we'll login.
  4. If nobody is found via meta or email, we assume the connecting user is a first-time visitor. We auto-create an account for them and log them in.
  5. Redirect the user to their previous page.
Note that all of the above is completely transparent - to the user, it appears that the current page was just reloaded and they're now logged in.

Hooks & Filters

During the login process, a number of hooks and filters provide an easy way for programmers to customize the script's behavior as needed:
  • Hook wpfb_prelogin runs at the very start of the login script, allowing you to perform custom actions before connecting to Facebook.
  • Hook wpfb_connect runs after connecting to Facebook but before searching for a local Wordpress user, letting you access profile information but still abort the process if desired.
  • Filter wpfb_insert_user is applied to userdata just before autoregistering an account, allowing you to customize new users without affecting existing ones.
  • Hook wpfb_existing_user runs before logging in an existing (i.e. not autoregistered) user.
  • Hook wpfb_login runs just before the login process finishes, receiving the user's Wordpress uid, their Facebook uid, and a Facebook API instance with active client session. This allows you to access and utilize social information about your visitors; see the examples below for more detailed instructions.
  • Hook wpfb_add_to_form allows you to insert html into the <form> responsible for sending the user to _process_login.php. This is handy if you want to forward additional data for use during the login process.
  • Hook wpfb_add_to_js lets you insert additional javascript to be executed before submitting the <form> that sends the user to _process_login.php.
  • Hook wpfb_add_to_asyncinit lets you insert additional javascript after the Facebook API initializes.
  • Filter wpfb_extended_permissions lets you modify the extended permissions that Facebook will prompt for. The complete list of available permissions is documented here.
  • Hook wpfb_after_button lets you output custom html immediately after the Login with Facebook button.

Examples

The hook wpfb_login receives an array of 3 arguments, formatted like this:
  • $args['WP_ID']: The local Wordpress userID
  • $args['FB_ID']: The Facebook userID
  • $args['facebook']: The Facebook API instance, with active client session
Because it provides a valid Facebook session and matching local blog user, it's easy to pull whatever information you need from their profile and utilize it on your local site. As an example, I'll check if I'm friends with the connecting user, and if so, add them to a special "Personal Friends" group (via the Role Scoper plugin):
add_action('wpfb_login', 'add_to_friends');
function add_to_friends($arg)
{
  $myUID = '123456';
  $newUID= $arg['FB_ID'];
  $rsGrp = 15;
  $fbArg = array('method'=>'friends.areFriends','uids1'=>$myUID,'uids2'=>$newUID);
  $result = $arg['facebook']->api( $fbArg );
  if( $result[0]['are_friends'] )
    ScoperAdminLib::add_group_user($rsGrp, $arg['WP_ID']);
}
For information on the types of things you can pull from Facebook, refer to the API documentation here.

The following is a slightly more advanced example of how you might use wpfb_add_to_js and wpfb_add_to_form to forward some custom data for use during the login process: 
//Add a POST variable to be sent through to _process_login.php
add_action('wpfb_add_to_form', 'nb_connect_add_to_form');
function nb_connect_add_to_form(){
  echo '<input type="hidden" name="cstm" id="cstm" value="unset" />';
}

//Before the form is submitted, use JS to set the field dynamically from a textbox
add_action('wpfb_add_to_js', 'nb_connect_add_to_js');
function nb_connect_add_to_js(){
  echo "document.getElementById('cstm').value = document.getElementById('t').value";
}
		
//When the user connects, insert the data into their BP xprofile.
add_action('wpfb_inserted_user', 'nb_connect_add_profiledata');
function nb_connect_add_profiledata($args)
{
  global $_POST;
  if( !function_exists('xprofile_set_field_data') ) return;
  xprofile_set_field_data('my_profile_field', $args['WP_ID'], $_POST['cstm']);
}

Custom Login Buttons

If you'd like to manually add a Facebook button elsewhere on your site, you may do so by calling the function: 
jfb_output_facebook_btn();
Note however that this relies on two other functions which are normally auto-invoked by wp_footer, jfb_output_facebook_callback() and jfb_output_facebook_init(). If you end up with a nonfunctional button, most likely you're on a page that doesn't call wp_footer so you'll need to explicitly call one or both of these yourself.

AutoPrompting

Normally, users will initiate a login by manually clicking the "Login with Facebook" button. But what if you want to prompt them automatically, as soon as they visit a page? What if you have some private content that only friends should be able to access? Rather than manually creating user accounts and instructing them to login before viewing the content, we can use WP-FB-AutoConnect to handle it all automatically. I've included a sample script, _autologin.php, which will let you provide a link like this:
http://www.example.com/autologin/192
When a user visits the link, if they already have access to post 192 it'll send them straight there, and if not, it'll auto-popup a Facebook Connect window, log them in, give them access, then redirect them. No manual intervention is required by either you or the user - all they need is the link.

Note that this is a fairly advanced usage that requires a good bit of PHP knowledge; it's provided just as an example of how you can further utilize the plugin. Please refer to _autologin.php for exactly how it works.

FAQ

Note: Numbers may not be sequential as I remove old or outdated FAQs.

2. The Login button isn't rendering correctly in IE.
Make sure your theme calls language_attributes() in its opening html tag.

3. The widget's layout doesn't look anything like yours.
This is a CSS issue - you'll need to style it appropriately in your theme's stylesheet. For reference, here are the rules I'm using - you can try this out, and alter it as needed:
#wp-submit{  height:23px; width:46px; padding:0; margin:0 0 0 7px; }
#user_pass{  height:18px; width:86px; padding: 3px; }
#user_login{ height:18px; width:86px; padding: 3px; }
#loginform label{ display:inline-block; width:2.75em; }
#rememberme{ border:0; padding:0; margin: 0 2px; background:none; }
#forgotText{ display:inline-block; margin-left:9px; height:26px; font-size:80%;}
.fbLoginButton{   display:block; height:18px; margin-top:7px; text-align:center; }
.wpfb-widget-avatar {float: left;}
.wpfb-widget-avatar img.avatar {float:none; margin:0; }
8. What if my theme doesn't support Widgets?
The right answer: update your theme. It's *very* easy to support them, and they've been around for ages.
The wrong answer: <?php the_widget("Widget_LoginLogout", array('title' => 'Login')); ?>

9. I'm getting a 404 server error while trying to execute _process_login.php.
Your FTP client is probably set to upload files with the wrong permissions - try changing _process_login.php and the parent directory to 755. You should be able to access _process_login.php directly and have it say "Please do not access this script directly." If not, that means your server isn't executing the php at all (and it's a problem with your server configuration rather than the plugin).

10. I'm getting a 500 internal server error while trying to execute _process_login.php
In order to find the cause of this issue, you'll need to view your raw server error logs (contact your webhost if you don't know how). 9 out of 10 times it's because some necessary module (like cURL) is missing or disabled.

11. I can't login - the popup always says "Invalid Argument", and something about a cross-domain receiver.
The Site URL you enter must match the base URL of your site. A common mistake is to have a website like http://example.com, but enter http://www.example.com. Also make sure you've entered it correctly in Wordpress under Settings -> General.

14. When I click the "Login with Facebook" button, nothing happens - no popup dialog.
Most likely your page has other javascript errors that are causing it to stop executing before it reaches the login button. Load it up with Firebug and see. For information on how to use Firebug, please visit Firebug.com.

17. Whenever I try to login, I get stuck with "You must be logged in to Facebook to use this feature."
You've probably disabled third-party cookies in your browser. Facebook Connect requires cookies.

19. I'm getting the error "Could not access the Facebook API client (failed on users_getInfo())"
This script requires that your server either have cURL installed or FOPEN enabled. If neither are available, it won't be able to contact Facebook. If you do have cURL but are getting "CurlException: 6: name lookup timed out", you can workaround it by modifying the Facebook library as documented here. If you're getting "CurlException: 60: SSL certificate problem," you can workaround it as documented here.

20. Whenever I try to connect, I get the error "Failed nonce check. Login aborted."
The "nonce" is a security feature builtin to Wordpress (see here), and not something I personally implemented. It's possible that something funky is going on with your cookies, or that a caching plugin is breaking this functionality. However, as I've never experienced the problem myself, and as nonces aren't specific to this plugin, I'm afraid I really can't tell you what your problem might be. If you simply can't figure it out and are desperate to get the plugin running, I've added a debug option to "DISABLE the nonce security check" - but note that I don't recommend using this as it will result in weakened security by skipping the nonce check entirely.

22. Can users who connected with this plugin also login manually (not via Facebook)?
Yes, an autoregistered user is the same as any other WP user. However, they'll need to login with Facebook once so they can edit their profile and set their own password. Alternatively, you can purchase the premium addon which can send a custom welcome message (along with login credentials) to autoregistered users.

23. I don't like the username/role/something about the autoregistered user accounts. Can you change it?
You're free to modify the userdata to whatever you'd like via the filters documented above.

24. "Login with Facebook" only appears as text, not a clickable button.
Either your theme isn't calling wp_footer or you've got other Javascript errors on your page (See FAQ14).

27. Why can't users who've connected with Facebook change their avatars anymore?
The option to use Facebook avatars cannot be overridden on a per-user basis. In other words, if enabled, all users who've connected with Facebook will see their profile picture rather than their Wordpress avatar.

28. What additional features are under consideration for the Premium add-on?
I maintain a complete list of feature requests on Fundry here. If you'd like to support/hasten a feature you can do so by pledging a small amount towards its development; otherwise, I'll address them in order of urgency, popularity, and ease. If you have another idea you'd like to see added you may leave a comment below, but please note that new features are only being implemented in the Premium add-on at this time.

30. Can I receive update notifications for the Premium addon? How do I perform the updates?
Whenever a new version is available, I'll announce it in the comment thread below and on the Facebook fanpage (admin panel notifications are in the works). Users will then have their remaining download counts refilled, and may grab the latest version from store.justin-klein.com (just like after the original purchase).

31. I've downloaded and installed the Premium addon, but I still can't access its features.
WP-FB-AutoConnect-Premium.php goes in your plugins directory (i.e. wp-content/plugins/WP-FB-AutoConnect-Premium.php), not the WP-FB-AutoConnect directory (i.e. wp-content/plugins/wp-fb-autoconnect/WP-FB-AutoConnect-Premium.php). This is to prevent it from getting overwritten when you auto-update the core plugin.

32. I've paid for the Premium addon, but the download link isn't available.
For the store to instantly confirm your purchase, you must use an instant payment method on Paypal. eChecks take 3-5 days to clear, so until that time the store will not auto-enable the download. If you did use an instant payment, it's possible that some "special characters" in your name or address have tripped up its notification system - if this is the case (extremely rare), I'll manually approve the order the next time I check my email.

33. When I updated to WP-FB-AutoConnect v2.1.0, everything stopped working.
Version 2.1 was the first to use Facebook's new 3.x SDK. If this broke your site, there are three likely causes:
  1. If you're a Premium user, you must also update your addon to v24 (or newer). See FAQ30 for how.
  2. If you have other Facebook plugins, make sure they're not still using the old SDK.
  3. If you've added your own actions or filters, make sure that calls into the Facebook API are up-to-date.
35. It doesn't seem to work in so-and-so browser.
Please reconfirm any browser-specific issues on another computer before reporting them below; 99% of the time they're caused by something on your local system. Make sure you tell me you've done this before reporting a browser bug, or I'll just redirect you to this FAQ. At the time of writing, this plugin has been tested on:
  • Windows: IE 7-9, Firefox 3-8, Chrome 10-15, Safari 4, Opera 10-11
  • Mac: Firefox 3-4, Chrome 11-12b, Safari 4-5
  • iPhone: Safari 4-5
  • Linux: Firefox 4
36. How can I modify the plugin to work a bit differently / How can I implement some not-included feature?
As this plugin is open-source, you're welcome to tinker and modify it as you like. However, I do not provide free support on customizations beyond what's included with the plugin. If you need customizations that you can't implement on your own, I suggest hiring myself or another experienced Wordpress developer to do so for you (or, see FAQ28). Note: asking me to tell you exactly what to add/modify is the same as asking me to do it myself.

37. Whenever someone tries to login, it says "Error: Failed to get the Facebook user session..."
This should be fixed since v2.1.0. If you're still experiencing it, please report it below and specifically mention what version you're using, and that you've tried it on the default theme with no other active plugins (see FAQ100).

38. Why isn't my login widget showing the connected user's avatar?
The option to show an avatar is available via the Premium widget only. If you're already a Premium customer but aren't seeing an avatar, head over to Appearance->Widgets in your admin panel and make sure you're using "WP-FB-AutoConnect Premium" (not "WP-FB-AutoConnect Basic"), and that the "Show Avatar" option is enabled.

100. Something else isn't working. What should I do?
  1. Try disabling *ALL* your other plugins and using the default theme; conflicting plugins and broken themes are by far the most common cause of problems. If that works, you should be able to pinpoint the source of the issue by reactivating them one at a time.
  2. Try deleting your Facebook application, recreating it from scratch, and re-configuring the plugin. Virtually every problem that isn't solved by #1 has been solved by this.
  3. If something still isn't working, you may post a question below - but make sure to specifically mention if you've tried it with the default theme, ALL other plugins off, and have tried recreating your app. Otherwise I'll just direct your attention to this FAQ.

Feedback/Support


If you have any support requests, please use the comment form below and I'll do my best to get back to you.

Important: Make sure to include a clear and detailed explanation of the problem; "It's not working" isn't enough for me to help. Also, please include the information from the "Support Info" tab of the plugin's admin panel, as well as answers to *ALL* of the following questions. If you choose to ignore this when reporting a bug, you may not get a reply:
  1. Have you tried disabling all your other plugins AND using the default theme (FAQ100)?
  2. Have you tried recreating your Facebook app and reconnecting it to the plugin (FAQ100)?
  3. Have you tried it in another browser (FAQ35)?
  4. Provide a link to the site that isn't working.
I've read and tried everything in the FAQs above, but am still having a problem.
Show the comment form >>

Advertise | Disclaimer
©2004-2012 Justin Klein
XHTML Valid
17:12:20 0.9s 99q 43.2m