Connect/How to Link Your Users to Facebook
From Facebook Developer Wiki
Before you begin, you should read Linking Your Users to Facebook to understand how you can best implement this feature.
Contents |
Identifying Your Users That Are on Facebook
Users Come to Your Site and Log in
Identifying a user that has a Facebook account is as simple as getting them to click the Connect with Facebook button on your site and retrieving their Facebook ID once they are authenticated.
Be sure to read our getting started document to learn how to retrieve this Facebook ID. Once you have the ID you'll want to store that ID with the user's account so you can identify the user the next time they log in. To do this effectively, you will want to consider running the batch script mentioned below to register and retrieve the "email_hashes" attribute associated with their account.
Identifying a User's Friends
Once you have identified the user, you can now get their friends that have also connected their Facebook accounts. To do this, simply call the friends.getAppUsers API call and Facebook will return to you a list of all the friends of the user that have connected already with your website.
Note: At this time, you may want to automatically add these individuals as friends in your database if your architecture supports it. Once you have this information you can start creating a social experience for your users.
Building a Social Experience for Those Users
Tracking the Experience of Your Users
There are two ways you can track the experience of your users:
- By tracking their activities and storing them in your own database.
- By using stream.get (filtered by your app ID) to identify their activity within Facebook using your site.
Once you're tracking their activities, you can easily display the activities of their other Facebook friends, encouraging much stronger participation on your site. You can use requests and invitations, along with FB.Connect.streamPublish to share those activities with their friends on Facebook, and more.
Encouraging Users to Invite Their Friends Not on Your Site
Facebook makes it easy to give your users the tools to invite their friends that aren't using your site to register. To do this, simply include an fb:request-form XFBML tag and a list of all their friends will be provided for them to invite to register through your site. Be sure to make the registration simple! A link straight to the Connect with Facebook code on your site should allow new users to simply click Accept in their invitation and be automatically registered.
Identifying and Inviting Your Existing Users to Connect
The first thing you are going to want to do after integrating Facebook Connect on your website is to identify which of your existing users also have Facebook accounts and register those with Facebook. Registering your users with Facebook accounts is simple if you have a little batch scripting skills. Here's how you do it:
- Retrieve a list of your users' email addresses (and optional account IDs or profile URLs) from your user database.
- Hash them appropriately using the instructions on connect.registerUsers.
- Store them in the array as specified on connect.registerUsers and send the Array to Facebook using the connect.registerUsers API call. Only 1,000 email addresses can be stored in the array per call.
- Your response will be an array of hashed email addresses that have already connected through your site.
- The next time a user logs into your site through Facebook you'll want to use users.getInfo to retrieve the "email_hashes" field from their account, and you can use that to now find which account is theirs in your database and store their Facebook ID with it.
Note: If that user deletes his or her account, you'll want to call connect.unregisterUsers to remove their association in Facebook's records as well. - You can now make API calls on their behalf. At this point you'll be able to use friends.getAppUsers to start linking them to their other friends on Facebook that have connected already to your website. You'll also want to encourage them to invite their other friends that are members of your site to connect through Facebook.
Use-Case Scenarios to Include in Your Application
There are 3 scenarios you will want to account for when integrating Facebook Connect into your website. Ensuring you cover each of these will allow you to provide the strongest social experience for all your users, and enable much less effort for your users to register and link their accounts with their friends.
User Has a Facebook Account, Is already Registered on Your Site
There are four ways you can encourage them to link their Facebook account. These methods assume you've run the batch script above:
- The user will get a Connect request invite when they log into Facebook, inviting them to connect their Facebook account. When they accept the request, your post-authorize URL is called and you can use users.getInfo to get the
email_hashesattribute for that user, match it to the user's account in your database, and associate their Facebook ID with their account in your database. - Provide a Connect with Facebook button for all your users to log in. When the user opts to log in through this method, you can then use users.getInfo to get the
email_hashesattribute for that user, match it to the user's account in your database, and associate their Facebook ID with their account in your database. - After the user logs in, you can provide a Connect with Facebook button somewhere on your site. When the user clicks this, you can retrieve their Facebook ID and associate it with their account in your database via their current session. (There is no need to call users.getInfo to get the
email_hashesattribute in this case.) - Encourage their friends to invite them. You can provide a simple invite form for each user that has connected through Facebook using either the XFBML tag, fb:connect-form, or by running the JavaScript client library call, FB.Connect.inviteConnectUsers when you want the invite dialog to appear. Through either method, a form appears showing all of the user's friends that have been registered, encouraging that user to invite those friends to Connect and show up in their list of friends on your website.
User Has a Facebook Account, Is not yet Registered on Your Site
In this case, the user can register on your site in one of three ways and have their account associated with Facebook:
- Click the Connect with Facebook button - this is the most straightforward way, and involves the least effort on your part. Some sites forgo their own registration altogether opting to replace it with this one-click registration.
To register the user, verify that they don't already have an account on your site by calling users.getInfo for the user and checking the
email_hashesattribute (matching their email address with their email in your database) after they have logged in through Facebook. If there were no matches, create a new user account in your database including just a minimum of their Facebook ID - if you want to include more information from the user you can do so later, but with their Facebook session and the Facebook API you can already access a great deal of information about the user from Facebook. That's it! - Register via your site's normal registration - when the user registers through your normal registration form, be sure to retrieve their email address, and when the user submits the form, call connect.registerUsers on that specific, hashed, email address. The minute they register on your site they will see a Connect request to connect with your site the next time they log into Facebook. You can then use users.getInfo to retrieve the
email_hashesattribute for that user and store their Facebook ID with their account in your database (by matching their email addresses). - Encourage their friends to invite them - even though they don't yet have an account on your site, you can provide an XFBML fb:request-form for your existing users who have connected their Facebook accounts with which they can invite their non-member friends. Ideally, you will want to use exclude-ids in your fb:multi-friend-selector or similar call to exclude those users the user has already invited, as well as any users that already have connected accounts on your system.
User Does not Have a Facebook Account
If the user does not have a Facebook account, you can still set their account aside for later in case they decide to join Facebook down the road. To do so, just call connect.registerUsers in the Facebook API with that user's hashed email address. Their account will now be registered with Facebook, and when they create a Facebook account with that email address, they will automatically be sent a Connect request for your site when they log in to Facebook for the first time. Just call users.getInfo at this point to retrieve the user's hashed email address, and match it with the email address they registered on your website, store their Facebook ID with their account, and now every time they log in through Facebook you can make API calls on their behalf.
Applying to Register Your Users' Accounts
Before you're able to use Connect.registerUsers to register your users' accounts, you'll need to enable the option in your Application settings. To do so:
- Go to your Application Settings.
- Click the Connect tab.
- Set Friend Linking Access to Requested.
- Under How site uses Friend Linking, describe how you plan to link your users.
- If your site already has some way to link users, set Native Friend Linking to Yes, and provide how you plan to use friend linking with those native methods.
