Yesterday I rolled out Facebook Connect for SpokenWord.org, and if you have a Facebook account I urge you to stop by, give it a try, and let us know if it works for you. The integration is about two-thirds done, but you probably won’t notice the missing one-third. It has been an interesting process so far. I previously implemented OpenID, and I expected something similar, but that’s not the case. The concepts of the two systems are similar, but the realities are quite different. For example:

• Facebook’s documentation is awful. Rather than one or two coherent documents there are dozens of wiki pages written, as far as I can tell, by the developers themselves, not good tech writers. Each page is written in a different style and documents (usually incompletely) one small piece of the big picture. To actually integrate Facebook into an existing identity system, there are many — more than becessary — moving parts.
• Although a FB user explicitly authorizes your application, FB refuses to supply his or her email address through the API. Instead, there’s a very Baroque system by which you send FB hashed versions of the email addresses of all your existing registered members in advance so that Facebook can then let you know that one of them matches a FB user at the time that user authorizes your application. But if a new (to you) FB user logs into your site, you don’t have that existing data. (OpenId’s API gives you an email address if the user approves.)
• The Facebook Terms of Service are oppressive. They must have been written by Facebook’s Business Prevention Division. For example, you are not allowed to store (in a database) any personal data you receive from Facebook Connect. When a user authorizes our app, FB sends us the user’s first and last names. We’re allowed to display those while the user is connected, but not thereafter. (We get around this by asking the user to give us this data independently.) I noticed that TechCrunch uses Facebook Connect for comments, so I was curious what would happen if I left a comment on their blog and then de-authorized the TechCrunch app. Sure enough, my comments disappeared from their site, and when I re-enabled the app, the comments re-appeared. Weird.
• The email thing is particularly nasty, for while we’re not sending FB our users’ emaill addresses unencrypted (which would violate our own Privacy Policy), we are sending an MD5 hash of those addresses. This means FB can compare the hashes we send them to the 100+ million email addresses they already have, allowing them to determine that someone is a registered members on our site even before that person authorizes the use of his/her FB identity to access our site.
• FB requires that if a user is logged in via Facebook, you display that user’s Facebook photo on every page they view. No reason is given for this requirement, and very few Facebook Connect sites do so. (Digg is an exception.) Note that this (and other ToS issues) requires that you load FB’s supporting JavaScript on every page.
• Oh, did I mention how bad their documentation is?

All of that said — and there are many more issues — we’ve had many requests for this integration as a way to make it easier to register for and login to SpokenWord.org. I hope you find it valuable.