Merge branch 'master' of gitorious.org:social/mainline into social-master

[quix0rs-gnu-social.git] / plugins / TwitterBridge / README

diff --git a/plugins/TwitterBridge/README b/plugins/TwitterBridge/README
index 09352188ed669965a9b51ece9ac848811c58915d..4f1f15c377b3eaac7d1df50a82a833f784be2690 100644 (file)
--- a/plugins/TwitterBridge/README
+++ b/plugins/TwitterBridge/README
@@ -1,48 +1,81 @@
+Twitter Bridge Plugin
+=====================
+

 This Twitter "bridge" plugin allows you to integrate your StatusNet
 instance with Twitter.  Installing it will allow your users to:
 
 This Twitter "bridge" plugin allows you to integrate your StatusNet
 instance with Twitter.  Installing it will allow your users to:
 

-    - automatically post notices to thier Twitter accounts
+    - automatically post notices to their Twitter accounts

     - automatically subscribe to other Twitter users who are also using
       your StatusNet install, if possible (requires running a daemon)
     - import their Twitter friends' tweets (requires running a daemon)
     - automatically subscribe to other Twitter users who are also using
       your StatusNet install, if possible (requires running a daemon)
     - import their Twitter friends' tweets (requires running a daemon)

+    - allow users to authenticate using Twitter ('Sign in with Twitter')

 
 Installation
 ------------
 
 
 Installation
 ------------
 

+OAuth 1.0a (http://oauth.net) is used to to access protected resources
+on Twitter. To use Twitter bridging you will need to register your
+instance of StatusNet as an application on Twitter (http://twitter.com/apps).
+During the application registration process your application will be assigned
+a "consumer" key and secret, which the plugin will use to make OAuth requests
+to Twitter. You can either pass the consumer key and secret in when you
+enable the plugin, or set it using the Twitter administration panel.
+
+When registering your application with Twitter set the type to "Browser"
+and your Callback URL to:
+
+    http://example.org/mublog/twitter/authorization
+
+(Change "example.org" to your site domain and "mublog" to your site
+path.)
+
+The default access type should be "Read & Write".
+

 To enable the plugin, add the following to your config.php:
 
 To enable the plugin, add the following to your config.php:
 

-    require_once(INSTALLDIR . '/plugins/TwitterBridge/TwitterBridgePlugin.php');
-    $tb = new TwitterBridgePlugin();
+    addPlugin(
+        'TwitterBridge',
+        array(
+            'consumer_key'    => 'YOUR_CONSUMER_KEY',
+            'consumer_secret' => 'YOUR_CONSUMER_SECRET'
+        )
+    );

 
 

-OAuth is used to to access protected resources on Twitter (as opposed to
-HTTP Basic Auth)*.  To use Twitter bridging you will need to register
-your instance of StatusNet as an application on Twitter
-(http://twitter.com/apps), and update the following variables in your
-config.php with the consumer key and secret Twitter generates for you:
+or if you want to set the variables from the website's administration panel:

 
 

-    $config['twitter']['consumer_key']    = 'YOURKEY';
-    $config['twitter']['consumer_secret'] = 'YOURSECRET';
+   addPlugin('TwitterBridge');

 
 

-When registering your application with Twitter set the type to "Browser"
-and your Callback URL to:
+After saving your configuration file, please run 'php scripts/upgrade.php'
+and also restart the background daemons if they are active on your instance.

 
 

-    http://example.org/mublog/twitter/authorization
+Administration panel
+--------------------
+
+To access the administration panel, you'll need to use a user with the
+"administrator" role (see: scripts/userrole.php).
+
+Sign in with Twitter
+--------------------
+
+GNU social optionally allows users to register and authenticate using their
+Twitter credentials via the "Sign in with Twitter" pattern described here:
+
+    https://dev.twitter.com/web/sign-in

 
 

-The default access type should be, "Read & Write".
+The option is _on_ by default when you install the plugin, but it can
+disabled via the Twitter bridge administration panel, or by adding the
+following line to your config.php:

 
 

-* Note: The plugin will still push notices to Twitter for users who
-  have previously setup the Twitter bridge using their Twitter name and
-  password under an older versions of StatusNet, but all new Twitter
-  bridge connections will use OAuth.
+    $config['twitter']['signin'] = false;

 
 

-Deamons
+Daemons

 -------
 
 -------
 

-For friend syncing and importing notices running two additional daemon
-scripts is necessary (synctwitterfriends.php and
-twitterstatusfetcher.php).
+For friend syncing and importing Twitter tweets, running two
+additional daemon scripts is necessary: synctwitterfriends.php and
+twitterstatusfetcher.php.

 
 

-In the daemons subidrectory of the plugin are three scripts:
+In the daemons subdirectory of the plugin are three scripts:

 
 * Twitter Friends Syncing (daemons/synctwitterfriends.php)
 
 
 * Twitter Friends Syncing (daemons/synctwitterfriends.php)
 


@@ -52,13 +85,13 @@ subscribe to "friends" (people they "follow") on Twitter who also have
 accounts on your StatusNet system, and who have previously set up a link
 for automatically posting notices to Twitter.
 
 accounts on your StatusNet system, and who have previously set up a link
 for automatically posting notices to Twitter.
 

-The plugin will try to start this daemon when you run
-scripts/startdaemons.sh.
+The plugin will start this daemon when you run scripts/startdaemons.sh.

 
 * Importing statuses from Twitter (daemons/twitterstatusfetcher.php)
 
 
 * Importing statuses from Twitter (daemons/twitterstatusfetcher.php)
 

-To allow your users to import their friends' Twitter statuses, you will
-need to enable the bidirectional Twitter bridge in your config.php:
+You can allow uses to enable importing of your friends' Twitter
+timelines either in the Twitter bridge administration panel or in your
+config.php using the following configuration line:

 
     $config['twitterimport']['enabled'] = true;
 
 
     $config['twitterimport']['enabled'] = true;
 


@@ -67,8 +100,9 @@ other daemons when you run scripts/startdaemons.sh.
 
 Additionally, you will want to set the integration source variable,
 which will keep notices posted to Twitter via StatusNet from looping
 
 Additionally, you will want to set the integration source variable,
 which will keep notices posted to Twitter via StatusNet from looping

-back.  The integration source should be set to the name of your
-application, exactly as you specified it on the settings page for your
+back.  You can do this in the Twitter bridge administration panel, or
+via config.php. The integration source should be set to the name of your
+application _exactly_ as you specified it on the settings page for your

 StatusNet application on Twitter, e.g.:
 
     $config['integration']['source'] = 'YourApp';
 StatusNet application on Twitter, e.g.:
 
     $config['integration']['source'] = 'YourApp';


@@ -80,7 +114,9 @@ set up Twitter bridging.
 
 It's not strictly necessary to run this queue handler, and sites that
 haven't enabled queuing are still able to push notices to Twitter, but
 
 It's not strictly necessary to run this queue handler, and sites that
 haven't enabled queuing are still able to push notices to Twitter, but

-for larger sites and sites that wish to improve performance, this
-script allows notices to be sent "offline" via a separate process.
+for larger sites and sites that wish to improve performance the script
+allows notices to be sent "offline" via a separate process.

 
 

-The plugin will start this script when you run scripts/startdaemons.sh.
+StatusNet will automatically use the TwitterQueueHandler if you have
+enabled the queuing subsystem.  See the "Queues and daemons" section of
+the main README file for more information about how to do that.