diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 343 |
1 files changed, 328 insertions, 15 deletions
@@ -1,22 +1,335 @@ -# Conversations+ +# Conversations -Conversations+: the improved version of [Conversations](https://github.com/siacs/Conversations/) +Conversations: the very last word in instant messaging + +[](https://play.google.com/store/apps/details?id=eu.siacs.conversations) [](http://www.amazon.com/dp/B00WD35AAC/) + + + +## Design principles + +* Be as beautiful and easy to use as possible without sacrificing security or + privacy +* Rely on existing, well established protocols (XMPP) +* Do not require a Google Account or specifically Google Cloud Messaging (GCM) +* Require as few permissions as possible ## Features -Of course Conversations+ supports [all features of Conversations](https://github.com/siacs/Conversations/#features) and in addition: +* End-to-end encryption with either [OTR](https://otr.cypherpunks.ca/) or [OpenPGP](http://www.openpgp.org/about_openpgp/) +* Send and receive images as well as other kind of files +* Share your location via an external [plug-in](https://play.google.com/store/apps/details?id=eu.siacs.conversations.sharelocation) +* Indication when your contact has read your message +* Intuitive UI that follows Android Design guidelines +* Pictures / Avatars for your Contacts +* Syncs with desktop client +* Conferences (with support for bookmarks) +* Address book integration +* Multiple accounts / unified inbox +* Very low impact on battery life + + +### XMPP Features + +Conversations works with every XMPP server out there. However XMPP is an +extensible protocol. These extensions are standardized as well in so called +XEP's. Conversations supports a couple of these to make the overall user +experience better. There is a chance that your current XMPP server does not +support these extensions; therefore to get the most out of Conversations you +should consider either switching to an XMPP server that does or — even better — +run your own XMPP server for you and your friends. These XEP's are: + +* XEP-0065: SOCKS5 Bytestreams (or mod_proxy65). Will be used to transfer + files if both parties are behind a firewall (NAT). +* XEP-0163: Personal Eventing Protocol for avatars +* XEP-0191: Blocking command lets you blacklist spammers or block contacts + without removing them from your roster. +* XEP-0198: Stream Management allows XMPP to survive small network outages and + changes of the underlying TCP connection. +* XEP-0280: Message Carbons which automatically syncs the messages you send to + your desktop client and thus allows you to switch seamlessly from your mobile + client to your desktop client and back within one conversation. +* XEP-0237: Roster Versioning mainly to save bandwidth on poor mobile connections +* XEP-0313: Message Archive Management synchronize message history with the + server. Catch up with messages that were sent while Conversations was + offline. +* XEP-0352: Client State Indication lets the server know whether or not + Conversations is in the background. Allows the server to save bandwidth by + withholding unimportant packages. +* XEP-xxxx: HttpUpload allows you to share files in conferences and with offline + contacts. Requires an [additional component](https://github.com/siacs/HttpUploadComponent) + on your server. + +## Team + +#### Head of Development + +* [Daniel Gultsch](https://github.com/inputmice) + +#### Code Contributions + +(In order of appearance) + +* [Rene Treffer](https://github.com/rtreffer) ([PRs](https://github.com/siacs/Conversations/pulls?utf8=%E2%9C%93&q=is%3Apr+author%3Artreffer+is%3Amerged)) +* [Andreas Straub](https://github.com/strb) ([PRs](https://github.com/siacs/Conversations/pulls?utf8=%E2%9C%93&q=is%3Apr+author%3Astrb+is%3Amerged)) +* [Alethea Butler](https://github.com/alethea) ([PRs](https://github.com/siacs/Conversations/pulls?utf8=%E2%9C%93&q=is%3Apr+author%3Aalethea+is%3Amerged)) +* [M. Dietrich](https://github.com/emdete) ([PRs](https://github.com/siacs/Conversations/pulls?utf8=%E2%9C%93&q=is%3Apr+author%3Aemdete+is%3Amerged)) +* [betheg](https://github.com/betheg) ([PRs](https://github.com/siacs/Conversations/pulls?utf8=%E2%9C%93&q=is%3Apr+author%3Abetheg+is%3Amerged)) +* [Sam Whited](https://github.com/SamWhited) ([PRs](https://github.com/siacs/Conversations/pulls?utf8=%E2%9C%93&q=is%3Apr+author%3ASamWhited+is%3Amerged)) +* [BrianBlade](https://github.com/BrianBlade) ([PRs](https://github.com/siacs/Conversations/pulls?utf8=%E2%9C%93&q=is%3Apr+author%3ABrianBlade+is%3Amerged)) + +#### Logo +* [Ilia Rostovtsev](https://github.com/qooob) (Progress) +* [Diego Turtulici](http://efesto.eigenlab.org/~diesys) (Original) + +#### Translations +Translations are managed on [Transifex](https://www.transifex.com/projects/p/conversations/) + +## FAQ + +### General + +#### How do I install Conversations? + +Conversations is entirely open source and licensed under GPLv3. So if you are a +software developer you can check out the sources from GitHub and use ant to +build your apk file. + +The more convenient way — which not only gives you automatic updates but also +supports the further development of Conversations — is to buy the App in the +Google [Play Store](https://play.google.com/store/apps/details?id=eu.siacs.conversations). + +Buying the App from the Play Store will also give you access to our [beta test](#beta). + +#### I don't have a Google Account but I would still like to make a contribution + +I accept donations over PayPal, Bitcoin and Flattr. For donations via PayPal you +can use the email address `donate@siacs.eu` or the button below. + +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=CW3SYT3KG5PDL) + +**Disclaimer:** I'm not a huge fan of PayPal and their business policies. For +larger contributions please get in touch with me beforehand and we can talk +about bank transfer (SEPA). + +My Bitcoin Address is: `1NxSU1YxYzJVDpX1rcESAA3NJki7kRgeeu` + + +[](https://flattr.com/submit/auto?user_id=inputmice&url=http%3A%2F%2Fconversations.siacs.eu&title=Conversations&tags=github&category=software) + +#### How do I create an account? + +XMPP, like email, is a federated protocol which means that there is not one +company you can create an 'official XMPP account' with. Instead there are +hundreds, or even thousands, of provider out there. To find one use a web search +engine of your choice. Or maybe your university has one. Or you can run your +own. Or ask a friend to run one. Once you've found one, you can use +Conversations to create an account. Just select 'register new account on server' +within the create account dialog. + +#### Where can I set up a custom hostname / port +Conversations will automatically look up the SRV records for your domain name +which can point to any hostname port combination. If your server doesn’t provide +those please contact your admin and have them read +[this](http://prosody.im/doc/dns#srv_records) + +#### Conversations doesn't work for me. Where can I get help? + +You can join our conference room on `conversations@conference.siacs.eu`. +A lot of people in there are able to answer basic questions about the usage of +Conversations or can provide you with tips on running your own XMPP server. If +you found a bug or your app crashes please read the Developer / Report Bugs +section of this document. + +#### I need professional support with Conversations or setting up my server + +I'm available for hire. Contact me at `inputmice@siacs.eu`. + +#### How does the address book integration work? + +The address book integration was designed to protect your privacy. Conversations +neither uploads contacts from your address book to your server nor fills your +address book with unnecessary contacts from your online roster. If you manually +add a Jabber ID to your phones address book Conversations will use the name and +the profile picture of this contact. To make the process of adding Jabber IDs to +your address book easier you can click on the profile picture in the contact +details within Conversations. This will start an "add to address book" intent +with the JID as the payload. This doesn't require Conversations to have write +permissions on your address book but also doesn't require you to copy/paste a +JID from one app to another. + +#### I get 'delivery failed' on my messages + +If you get delivery failed on images it's probably because the recipient lost +network connectivity during reception. In that case you can try it again at a +later time. + +For text messages the answer to your question is a little bit more complex. +When you see 'delivery failed' on text messages, it is always something that is +being reported by the server. The most common reason for this is that the +recipient failed to resume a connection. When a client loses connectivity for a +short time the client usually has a five minute window to pick up that +connection again. When the client fails to do so because the network +connectivity is out for longer than that all messages sent to that client will +be returned to the sender resulting in a delivery failed. + +Other less common reasons are that the message you sent didn't meet some +criteria enforced by the server (too large, too many). Another reason could be +that the recipient is offline and the server doesn't provide offline storage. + +Usually you are able to distinguish between these two groups in the fact that +the first one happens always after some time and the second one happens almost +instantly. + +#### Where can I see the status of my contacts? How can I set a status or priority? + +Statuses are a horrible metric. Setting them manually to a proper value rarely +works because users are either lazy or just forget about them. Setting them +automatically does not provide quality results either. Keyboard or mouse +activity as indicator for example fails when the user is just looking at +something (reading an article, watching a movie). Furthermore automatic setting +of status always implies an impact on your privacy (are you sure you want +everybody in your contact list to know that you have been using your computer at +4am‽). + +In the past status has been used to judge the likelihood of whether or not your +messages are being read. This is no longer necessary. With Chat Markers +(XEP-0333, supported by Conversations since 0.4) we have the ability to **know** +whether or not your messages are being read. Similar things can be said for +priorities. In the past priorities have been used (by servers, not by clients!) +to route your messages to one specific client. With carbon messages (XEP-0280, +supported by Conversations since 0.1) this is no longer necessary. Using +priorities to route OTR messages isn't practical either because they are not +changeable on the fly. Metrics like last active client (the client which sent +the last message) are much better. + +Unfortunately these modern replacements for legacy XMPP features are not widely +adopted. However Conversations should be an instant messenger for the future and +instead of making Conversations compatible with the past we should work on +implementing new, improved technologies and getting them into other XMPP clients +as well. + +Making these status and priority optional isn't a solution either because +Conversations is trying to get rid of old behaviours and set an example for +other clients. + +#### Conversations is missing a certain feature + +I'm open for new feature suggestions. You can use the [issue tracker][issues] on +GitHub. Please take some time to browse through the issues to see if someone +else already suggested it. Be assured that I read each and every ticket. If I +like it I will leave it open until it's implemented. If I don't like it I will +close it (usually with a short comment). If I don't comment on an feature +request that's probably a good sign because this means I agree with you. +Commenting with +1 on either open or closed issues won't change my mind, nor +will it accelerate the development. + +#### You closed my feature request but I want it really really badly + +Just write it yourself and send me a pull request. If I like it I will happily +merge it if I don't at least you and like minded people get to enjoy it. + +#### I need a feature and I need it now! + +I am available for hire. Contact me via XMPP: `inputmice@siacs.eu` + +### Security + +#### Why are there two end-to-end encryption methods and which one should I choose? + +In most cases OTR should be the encryption method of choice. It works out of the +box with most contacts as long as they are online. However PGP can, in some +cases, (message carbons to multiple clients) be more flexible. + +#### How do I use OpenPGP + +Before you continue reading you should note that the OpenPGP support in +Conversations is experimental. This is not because it will make the app unstable +but because the fundamental concepts of PGP aren't ready for widespread use. +The way PGP works is that you trust Key IDs instead of JID's or email addresses. +So in theory your contact list should consist of Public-Key-IDs instead of +JID's. But of course no email or XMPP client out there implements these +concepts. Plus PGP in the context of instant messaging has a couple of +downsides: It is vulnerable to replay attacks, it is rather verbose, and +decrypting and encrypting takes longer than OTR. It is however asynchronous and +works well with message carbons. + +To use OpenPGP you have to install the open source app +[OpenKeychain](http://www.openkeychain.org) and then long press on the account in +manage accounts and choose renew PGP announcement from the contextual menu. + +#### How does the encryption for conferences work? + +For conferences the only supported encryption method is OpenPGP (OTR does not +work with multiple participants). Every participant has to announce their +OpenPGP key (see answer above). If you would like to send encrypted messages to +a conference you have to make sure that you have every participant's public key +in your OpenKeychain. Right now there is no check in Conversations to ensure +that. You have to take care of that yourself. Go to the conference details and +touch every key id (The hexadecimal number below a contact). This will send you +to OpenKeychain which will assist you on adding the key. This works best in +very small conferences with contacts you are already using OpenPGP with. This +feature is regarded experimental. Conversations is the only client that uses +XEP-0027 with conferences. (The XEP neither specifically allows nor disallows +this.) + +### Development + +<a name="beta"></a> +#### Beta testing +If you bought the App on [Google Play](https://play.google.com/store/apps/details?id=eu.siacs.conversations) +you can get access to the latest beta version by joining the +[Conversations Beta Testers](https://plus.google.com/communities/107649347599361240873) +community on Google+ and then using [this link](https://play.google.com/apps/testing/eu.siacs.conversations) +to sign up for the beta test. + +#### How do I build Conversations + +Make sure to have ANDROID_HOME point to your Android SDK + + git clone https://github.com/siacs/Conversations.git + cd Conversations + ./gradlew build + + +[](https://travis-ci.org/siacs/Conversations) + +### How do I update/add external libraries? + +If the library you want to update is in Maven Central or JCenter (or has its own +Maven repo), add it or update its version in `build.gradle`. If the library is +in the `libs/` directory, you can update it using a subtree merge by doing the +following (using `minidns` as an example): + + git remote add minidns https://github.com/rtreffer/minidns.git + git fetch minidns + git merge -s subtree minidns master + +To add a new dependency to the `libs/` directory (replacing "name", "branch" and +"url" as necessary): + + git remote add name url + git merge -s ours --no-commit name/branch + git read-tree --prefix=libs/name -u name/branch + git commit -m "Subtree merged in name" + +#### How do I debug Conversations + +If something goes wrong Conversations usually exposes very little information in +the UI (other than the fact that something didn't work). However with adb +(android debug bridge) you squeeze some more information out of Conversations. +These information are especially useful if you are experiencing trouble with +your connection or with file transfer. + + adb -d logcat -v time -s conversations -* smileys like Whatsapp -* change of LED notification color -* online status in contact and conversation list +#### I found a bug -## Modifications +Please report it to our [issue tracker][issues]. If your app crashes please +provide a stack trace. If you are experiencing misbehaviour please provide +detailed steps to reproduce. Always mention whether you are running the latest +Play Store version or the current HEAD. If you are having problems connecting to +your XMPP server your file transfer doesn’t work as expected please always +include a logcat debug output with your issue (see above). -* unread count badges take care of setting "Conference notifications" -* swipe to end conversation only in one direction -* replace ASCII-smileys -* settings - * confirmation for received and/or read messages - * automatically download picture links - * automatically download only when wifi enabled -* bugfixes and code improvements +[issues]: https://github.com/siacs/Conversations/issues |