plugins/TwitterBridge/README

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