Linking Accounts and Finding Friends
From Facebook Developer Wiki
If you are not using Facebook Connect as your primary login, you can still use it to augment existing accounts on your site.
You can also use Facebook Connect to show a user which of their Facebook friends are on your site, and let them invite more of their Facebook friends onto your site.
Contents |
[edit] Authentication
You can use Facebook Connect as an alternate login mechanism for existing accounts on your site. The simplest way to achieve this is as follows:
- Create a table that maps a Facebook user ID to your own internal account identifier.
- When a user first connects with your site, add an entry to that table mapping the user’s Facebook user ID to their local identifier. There are two ways to achieve this:
- If you have previously registered the user’s email address and account information via connect.registerUsers you can query for this information once the user has connected and use it to create an association. The easiest place to do this would be in the Post-Authorize URL callback. See Suggesting Linked Accounts, below, for more details.
- When a user first visits your site after connecting, you can prompt them to look up any existing accounts that user might have and explicitly link them
- On subsequent site visits, use the Facebook UID to look up your local account identifier and automatically log the user in. If you are not using the Facebook PHP client library, please read Verifying The Signature to learn how to verify the integrity of the Facebook UID on the server-side (since it would be possible for the user to modify the UID using a JavaScript debugger).
Note: If you do not use Facebook for login, the user must still be logged in to Facebook for the Facebook Connect library to retrieve data on their behalf. To solve this, you can use either of two approaches:
- Prompting logged-out users to also log in to Facebook – if a user is logged-in to your site but not logged-in to Facebook, you can prompt them to also log in to Facebook (see Logging In And Connecting).
- Requesting "offline access" – you can request the
offline_accesspermission using either FB.Connect.showPermissionDialog or fb:prompt-permission. Both calls grant a long-lived session to the application. Because users may be reluctant to grant this permission for your application, it is not a generally recommended approach.
[edit] Friend Linking
One of the more powerful features of Facebook Connect is to suggest linked accounts. This allows users to easily find and invite their friends who are already on your site, as well as eases the process of linking up a Facebook account with a local account on your site.
Example Scenario: Your website, FooBar.com, has its own account registration. FooBar has 2 users, Anne and Bob. Anne and Bob are friends on Facebook, and both have signed up for accounts on FooBar. Anne decides she would like to connect account via Facebook Connect to get the added benefits of connecting with FooBar. Using the connect.registerUsers API method, Bob will be suggested to Anne, inviting Anne to send a Connect request to Bob. This enables FooBar (or your newly established Connect website) to spread through the Facebook social graph more quickly than if every user was required to organically find and connect with FooBar.
To enable friend linking fully, complete these steps.
[edit] Step 1: Getting Approval to Link Accounts
Before you can link accounts, Facebook must approve your site. Follow these steps.
- In the Facebook Developer application, edit your application settings. On the Connect tab, select the Requested radio button for Friend Linking Access.
- Describe how your site plans to implement friend linking.
- If you plan to use a contact importer or some other method to find friends, select Yes for Native Friend Linking, then provide a URL or a description of your native friend linking process.
- Save your changes.
[edit] Step 2: Suggesting Linked Accounts
First, suggest possible connections between your site's users and Facebook's users. To do this, you can use the connect.registerUsers API method. This allows you to pass a hash of the user's email address and some additional account identification information to suggest a possible connection between a user account on your site and a Facebook user account.
A typical use of this method would be to call it on existing users of your site in a series of overnight batch jobs until all users have been registered, and to then call it when new users register for your site that aren't yet using Facebook Connect.
[edit] Step 3: Sending Connect Invites
Once you have suggested a set of linked accounts via connect.registerUsers, you can then have users invite their friends to connect their accounts. This will help to complete your social graph and improve social filters and information distribution on your site.
To allow users to invite their friends, you can either use the FB.Connect.inviteConnectUsers method, or embed the fb:connect-form in your site using XFBML. If you want to determine whether or not the user has any potential friends to invite, you can call the connect.getUnconnectedFriendsCount method (either in JavaScript or PHP) to see if the user has any friends available to invite.
They can also invite their Facebook friends onto your site if they're not there already, using the normal invite mechanism, the Multi_friend_selector, provided by the API. The functionality of both this as well as the connect-form tag are shown in the example Connect site provided, The Run Around, of which the source code is available.
[edit] Step 4: Accepting Requests / First Time Login
When a user accepts a Connect request or logs into your site for the first time, Facebook will call the Post-Authorize URL (specified in your application settings) to alert your application that a new user has logged in. When you receive this callback, you can call fql.query on the FQL user table or users.getInfo to lookup the user's email_hashes (the hashes were registered using connect.registerUsers in step 1) and create an association between the Facebook user ID and the user's identifier on your site.
If you want to see which friends have already connected on your site, you can use the friends.getAppUsers API method.

