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