doc/Installing-Connectors.md

   1 Installing Connectors (Facebook/Twitter/StatusNet)
   2 ==================================================
   3
   4 * [Home](help)
   5
   6
   7 Friendica uses plugins to provide connectivity to some networks, such as Facebook and Twitter.
   8
   9 There is also a plugin to post through to an existing account on a StatusNet service.
  10 You only need this to post to an already existing StatusNet account, but not to communicate with StatusNet members in general.
  11
  12 All three plugins require an account on the target network.
  13 In addition you (or typically the server administrator) will need to obtain an API key to provide authenticated access to your Friendica server.
  14
  15 Site Configuration
  16 ---
  17
  18 Plugins must be installed by the site administrator before they can be used.
  19 This is accomplished through the site administration panel.
  20
  21 Each of the connectors also requires an "API key" from the service you wish to connect with.
  22 Some plugins allow you to enter this information in the site administration pages, while others may require you to edit your configuration file (.htconfig.php).
  23 The ways to obtain these keys vary between the services, but they all require an existing account on the target service.
  24 Once installed, these API keys can usually be shared by all site members.
  25
  26 The details of configuring each service follow (much of this information comes directly from the plugin source files):
  27
  28 Twitter Plugin for Friendica
  29 ---
  30
  31 * Author: Tobias Diekershoff
  32 * tobias.diekershoff@gmx.net
  33 * License: 3-clause BSD license
  34
  35 ###Configuration
  36 To use this plugin you need a OAuth Consumer key pair (key & secret).
  37 You can get it from [Twitter](https://twitter.com/apps).
  38
  39 Register your Friendica site as "Client" application with "Read & Write" access.
  40 We do not need "Twitter as login".
  41 When you've registered the app you get a key pair with an OAuth Consumer key and a secret key for your application/site.
  42 Add this key pair to your global .htconfig.php:
  43
  44         $a->config['twitter']['consumerkey'] = 'your consumer_key here';
  45         $a->config['twitter']['consumersecret'] = 'your consumer_secret here';
  46
  47 After this, your users can configure their Twitter account settings from "Settings -> Connector Settings".
  48
  49 ###More documentation
  50
  51 Find the author's documentation here: [http://diekershoff.homeunix.net/redmine/wiki/friendikaplugin/Twitter_Plugin](http://diekershoff.homeunix.net/redmine/wiki/friendikaplugin/Twitter_Plugin)
  52
  53
  54 StatusNet Plugin for Friendica
  55 ---
  56
  57 * Author: Tobias Diekershoff
  58 * tobias.diekershoff@gmx.net
  59 * License: 3-clause BSD license
  60
  61 ###Configuration
  62
  63 When the addon is activated the user has to aquire the following in order to connect to the StatusNet account of choice.
  64
  65 * The base URL for the StatusNet API, for identi.ca this is https://identi.ca/api/
  66 * OAuth Consumer key & secret
  67
  68 To get the OAuth Consumer key pair the user has to
  69
  70 1 ask her Friendica admin if a pair already exists or
  71 2 has to register the Friendica server as a client application on the StatusNet server.
  72
  73 This can be done from the account settings under "Settings -> Connections -> Register an OAuth client application -> Register a new application" on the StatusNet server.
  74
  75 During the registration of the OAuth client remember the following:
  76
  77 * Application names must be unique on the StatusNet site, so we recommend a Name of 'friendica-nnnn', replace 'nnnn' with a random number or your website name.
  78 * there is no callback url
  79 * register a desktop client
  80 * with read & write access
  81 * the Source URL should be the URL of your Friendica server
  82
  83 After the required credentials for the application are stored in the configuration you have to actually connect your Friendica account with StatusNet.
  84 This is done from the Settings -> Connector Settings page.
  85 Follow the Sign in with StatusNet button, allow access and then copy the security code into the box provided.
  86 Friendica will then try to acquire the final OAuth credentials from the API.
  87
  88 If successful, the addon settings will allow you to select to post your public messages to your StatusNet account (have a look behind the little lock symbol beneath the status "editor" on your Home or Network pages).
  89
  90 ###More documentation
  91
  92 Find the author's documentation here: [http://diekershoff.homeunix.net/redmine/wiki/friendikaplugin/StatusNet_Plugin](http://diekershoff.homeunix.net/redmine/wiki/friendikaplugin/StatusNet_Plugin)
  93
  94 The Friendica/Facebook connector
  95 ---
  96
  97 ###Configuration
  98
  99 First, register an API key for your site on [Facebook](developer.facebook.com).
 100 This requires a Facebook account, and may require additional authentication in the form of credit card or mobile phone verification.
 101
 102 We'd be very happy if you include "Friendica" in the application name to increase name recognition.
 103 The Friendica icons are also present in the images directory and may be uploaded as a Facebook app icon.
 104 Use images/friendica-16.jpg for the Icon and images/friendica-128.jpg for the logo.
 105
 106 The url should be your site URL with a trailing slash.
 107
 108 You **may** be required to provide a privacy and/or terms of service URL.
 109
 110 Navigate to Set Web->Site URL & Domain -> Website Settings.
 111 Set Site URL to yoursubdomain.yourdomain.com.
 112 Set Site Domain to your yourdomain.com.
 113
 114 Install the Facebook plugin on your Friendica site at 'admin/plugins'.
 115 You should then see a link for Facebook under 'Plugin Features' on the sidebar of the admin panel.
 116 Select it.
 117
 118 Enter the App-ID and App Secret that Facebook gave you.
 119 Change any other settings as desired.
 120
 121 On Friendica, each member who wishes to use the Facebook connector should visit the Facebook Settings section of their "Settings->Connector Settings" page, and click 'Install Facebook Connector'.
 122
 123 Choose the appropriate settings for your usage and privacy requirements.
 124
 125 This will ask you to log into Facebook and grant permission to the plugin to do its stuff.
 126 Allow it to do so.
 127
 128 You're done.
 129
 130 To turn it off visit the Connector Settings page again and 'Remove Facebook posting'.
 131
 132 Videos and embeds will not be posted if there is no other content.
 133 Links and images will be converted to a format suitable for the Facebook API and long posts truncated - with a link to view the full post.
 134
 135 Facebook contacts will also not be able to view "private" photos, as they are not able to authenticate to your site.
 136 We will address this in a future release.