plugins/TwitterBridge/README

   1 This Twitter "bridge" plugin allows you to integrate your StatusNet
   2 instance with Twitter.  Installing it will allow your users to:
   3
   4     - automatically post notices to their Twitter accounts
   5     - automatically subscribe to other Twitter users who are also using
   6       your StatusNet install, if possible (requires running a daemon)
   7     - import their Twitter friends' tweets (requires running a daemon)
   8     - allow users to authenticate using Twitter ('Sign in with Twitter')
   9
  10 Installation
  11 ------------
  12
  13 OAuth 1.0a (http://oauth.net) is used to to access protected resources
  14 on Twitter (as opposed to HTTP Basic Auth)*.  To use Twitter bridging
  15 you will need to register your instance of StatusNet as an application
  16 on Twitter (http://twitter.com/apps).  During the application
  17 registration process your application will be assigned a "consumer" key
  18 and secret, which the plugin will use to make OAuth requests to Twitter.
  19 You can either pass the consumer key and secret in when you enable the
  20 plugin, or set it using the Twitter administration panel.
  21
  22 When registering your application with Twitter set the type to "Browser"
  23 and your Callback URL to:
  24
  25     http://example.org/mublog/twitter/authorization
  26
  27 (Change "example.org" to your site domain and "mublog" to your site
  28 path.)
  29
  30 The default access type should be "Read & Write".
  31
  32 To enable the plugin, add the following to your config.php:
  33
  34     addPlugin(
  35         'TwitterBridge',
  36         array(
  37             'consumer_key'    => 'YOUR_CONSUMER_KEY',
  38             'consumer_secret' => 'YOUR_CONSUMER_SECRET'
  39         )
  40     );
  41
  42 * Note: The plugin will still push notices to Twitter for users who
  43   have previously set up the Twitter bridge using their Twitter name and
  44   password under an older version of StatusNet, but all new Twitter
  45   bridge connections will use OAuth.
  46
  47 Admin panel
  48 -----------
  49
  50 As of StatusNet 0.9.0 there is a new administration panel that allows
  51 you to configure Twitter bridge settings within StatusNet itself,
  52 instead of having to specify them manually in your config.php.  To enable
  53 the administration panel, you will need to add it to the list of active
  54 administration panels.  You can do this via your config.php. E.g.:
  55
  56     $config['admin']['panels'][] = 'twitter';
  57
  58 And to access it, you'll need to use a user with the "administrator"
  59 role (see: scripts/userrole.php).
  60
  61 Sign in with Twitter
  62 --------------------
  63
  64 As of 0.9.0 you StatusNet optionally allows users to register and
  65 authenticate using their Twitter credentials via the "Sign in with
  66 Twitter" pattern described here:
  67
  68     http://apiwiki.twitter.com/Sign-in-with-Twitter
  69
  70 The option is _on_ by default when you install the plugin, but it can
  71 disabled via the Twitter bridge admin panel, or by adding the following
  72 line to your config.php:
  73
  74     $config['twitter']['signin'] = false;
  75
  76 Daemons
  77 -------
  78
  79 For friend syncing and importing Twitter tweets, running two
  80 additional daemon scripts is necessary: synctwitterfriends.php and
  81 twitterstatusfetcher.php.
  82
  83 In the daemons subdirectory of the plugin are three scripts:
  84
  85 * Twitter Friends Syncing (daemons/synctwitterfriends.php)
  86
  87 Users may set a flag in their settings ("Subscribe to my Twitter friends
  88 here" under the Twitter tab) to have StatusNet attempt to locate and
  89 subscribe to "friends" (people they "follow") on Twitter who also have
  90 accounts on your StatusNet system, and who have previously set up a link
  91 for automatically posting notices to Twitter.
  92
  93 The plugin will start this daemon when you run scripts/startdaemons.sh.
  94
  95 * Importing statuses from Twitter (daemons/twitterstatusfetcher.php)
  96
  97 You can allow uses to enable importing of your friends' Twitter
  98 timelines either in the Twitter bridge administration panel or in your
  99 config.php using the following configuration line:
 100
 101     $config['twitterimport']['enabled'] = true;
 102
 103 The plugin will then start the TwitterStatusFetcher daemon along with the
 104 other daemons when you run scripts/startdaemons.sh.
 105
 106 Additionally, you will want to set the integration source variable,
 107 which will keep notices posted to Twitter via StatusNet from looping
 108 back.  You can do this in the Twitter bridge administration panel, or
 109 via config.php. The integration source should be set to the name of your
 110 application _exactly_ as you specified it on the settings page for your
 111 StatusNet application on Twitter, e.g.:
 112
 113     $config['integration']['source'] = 'YourApp';
 114
 115 * TwitterQueueHandler (daemons/twitterqueuehandler.php)
 116
 117 This script sends queued notices to Twitter for user who have opted to
 118 set up Twitter bridging.
 119
 120 It's not strictly necessary to run this queue handler, and sites that
 121 haven't enabled queuing are still able to push notices to Twitter, but
 122 for larger sites and sites that wish to improve performance, this script
 123 allows notices to be sent "offline" via a separate process.
 124
 125 StatusNet will automatically use the TwitterQueueHandler if you have
 126 enabled the queuing system.  See the "Queues and daemons" section of the
 127 main README file for more information about how to do that.