+Facebook Plugin
+===============
-// Facebook plugin
-require_once(INSTALLDIR . '/plugins/Facebook/FacebookPlugin.php');
-$fb = new FacebookPlugin();
+This plugin allows you to use Facebook Connect with StatusNet, provides
+a Facebook canvas application for your users, and allows them to update
+their Facebook statuses from StatusNet.
+Facebook Connect
+----------------
-TODO:
+Facebook connect allows users to register and login using nothing but their
+Facebook credentials. With Facebook Connect, your users can:
-- Integrate this and the FB Connect plugin
\ No newline at end of file
+- Authenticate (register/login/logout -- works similar to OpenID)
+- Associate an existing StatusNet account with a Facebook account
+- Disconnect a Facebook account from a StatusNet account
+
+Built-in Facebook Application
+-----------------------------
+
+The plugin also installs a StatusNet Facebook canvas application that
+allows your users to automatically update their Facebook status with
+their latest notices, invite their friends to use the app (and thus your
+site), view their notice timelines and post notices -- all from within
+Facebook. The application is built into the StatusNet Facebook plugin
+and runs on your host.
+
+Quick setup instructions*
+-------------------------
+
+Install the Facebook Developer application on Facebook:
+
+ http://www.facebook.com/developers/
+
+Use it to create a new application and generate an API key and secret.
+You will need the key and secret so cut-n-paste them into your text
+editor or write them down.
+
+In Facebook's application editor, specify the following URLs for your app:
+
+- Canvas Callback URL : http://example.net/mublog/facebook/app/
+- Post-Remove Callback URL: http://example.net/mublog/facebook/app/remove
+- Post-Add Redirect URL : http://apps.facebook.com/yourapp/
+- Canvas Page URL : http://apps.facebook.com/yourapp/
+- Connect URL : http://example.net/mublog/
+
+ *** ATTENTION ***
+ These URLs have changed slightly since StatusNet version 0.8.1,
+ so if you have been using the Facebook app previously, you will
+ need to update your configuration!
+
+Replace "example.net" with your host's URL, "mublog" with the path to your
+StatusNet installation, and 'yourapp' with the name of the Facebook
+application you created. (If you don't have "Fancy URLs" on, you'll need to
+change http://example.net/mublog/ to http://example.net/mublog/index.php/).
+
+Additionally, Choose "Web" for Application type in the Advanced tab. In the
+"Canvas setting" section, choose the "FBML" for Render Method, "Smart Size"
+for IFrame size, and "Full width (760px)" for Canvas Width. Everything else
+can be left with default values.
+
+* NOTE: For more under-the-hood detailed instructions about setting up a
+ Facebook application and getting an API key, check out the
+ following pages on the Facebook wiki:
+
+ http://wiki.developers.facebook.com/index.php/Connect/Setting_Up_Your_Site
+ http://wiki.developers.facebook.com/index.php/Creating_your_first_application
+
+Finally you must activate the plugin by adding it in your config.php
+(this is where you'll need the API key and secret generated earlier):
+
+ addPlugin(
+ 'Facebook',
+ array(
+ 'apikey' => 'YOUR_APIKEY',
+ 'secret' => 'YOUR_SECRET'
+ )
+ );
+
+Administration Panel
+--------------------
+
+As of StatusNet 0.9.0 you can alternatively specify the key and secret
+via a Facebook administration panel from within StatusNet, in which case
+you can just add:
+
+ addPlugin('Facebook');
+
+to activate the plugin.
+
+NOTE: To enable the administration panel you'll need to add it to the
+list of active administration panels, e.g.:
+
+ $config['admin']['panels'][] = 'facebook';
+
+and of course you'll need a user with the administrative role to access
+it and input the API key and secret (see: scripts/userrole.php).
+
+Testing It Out
+--------------
+
+If the Facebook plugin is enabled and working, there will be a new Facebook
+Connect Settings tab under each user's Connect menu. Users can connect and
+disconnect* to their Facebook accounts from it.
+
+To try out the plugin, fire up your browser and connect to:
+
+ http://example.net/mublog/main/facebooklogin
+
+or, if you do not have fancy URLs turned on:
+
+ http://example.net/mublog/index.php/main/facebooklogin
+
+You should see a page with a blue button that says: "Connect with Facebook"
+and you should be able to login or register.
+
+From within Facebook, you should also be able to get to the Facebook
+application, and run it by hitting the link you specified above when
+configuring it:
+
+ http://apps.facebook.com/yourapp/
+
+That link should be present you with a login screen. After logging in to
+the app, you are given the option to update their Facebook status via
+StatusNet.
+
+* Note: Before a user can disconnect from Facebook, she must set a normal
+ StatusNet password. Otherwise, she might not be able to login in to her
+ account in the future. This is usually only required for users who have
+ used Facebook Connect to register their StatusNet account, and therefore
+ haven't already set a local password.
+
+Offline Queue Handling
+----------------------
+
+For larger sites needing better performance it's possible to enable
+queuing and have users' notices posted to Facebook via a separate
+"offline" process -- FacebookQueueHandler (facebookqueuhandler.php in
+the Facebook plugin directory). It will run automatically if you have
+enabled StatusNet's offline queueing subsystem. See the "Queues and
+daemons" section in the StatusNet README for more about queuing.
+
+
+TODO
+----
+
+- Make Facebook Connect work for authentication for multi-site setups
+ (e.g.: *.status.net)
+- Posting to Facebook user streams using only Facebook Connect
+- Invite Facebook friends to use your StatusNet installation via Facebook
+ Connect
+- Auto-subscribe Facebook friends already using StatusNet
+- Share StatusNet favorite notices to your Facebook stream
+- Allow users to update their Facebook statuses once they have authenticated
+ with Facebook Connect (no need for them to use the Facebook app if they
+ don't want to).
+- Import a user's Facebook updates into StatusNet
projects / quix0rs-gnu-social.git / blobdiff