Merge pull request #217 from nextcloud/format-and-update-readme

## How to use this library

1) Add this library to your project

### 1) Add this library to your project

```gradle

repositories {

}

dependencies {

	implementation "com.github.nextcloud:Android-SingleSignOn:0.4.1"

    implementation "com.github.nextcloud:Android-SingleSignOn:0.5.1"

}

compileOptions {

We use some features from Java 8, so your project needs also to be compiled with (at least) this version.

2) To choose an account, include the following code in your login dialog:

### 2) To choose an account, include the following code in your login dialog:

From an Activity

private void openAccountChooser() {

    try {

        AccountImporter.pickNewAccount(this);

        } 

        catch (NextcloudFilesAppNotInstalledException e) {

            UiExceptionManager.showDialogForException(this, e);

        } catch (AndroidGetAccountsPermissionNotGranted e) {

    } catch (NextcloudFilesAppNotInstalledException | AndroidGetAccountsPermissionNotGranted e) {

        UiExceptionManager.showDialogForException(this, e);

    }

}

private void openAccountChooser() {

    try {

        AccountImporter.pickNewAccount(currentFragment);

        } catch (NextcloudFilesAppNotInstalledException e) {

            UiExceptionManager.showDialogForException(this, e);

        } catch (AndroidGetAccountsPermissionNotGranted e) {

    } catch (NextcloudFilesAppNotInstalledException | AndroidGetAccountsPermissionNotGranted e) {

        UiExceptionManager.showDialogForException(this, e);

    }

}

```

3) To handle the result of the Account Chooser, include the following:

### 3) To handle the result of the Account Chooser, include the following:

From an Activity

        NextcloudAPI.ApiConnectedListener callback = new NextcloudAPI.ApiConnectedListener() {

            @Override

            public void onConnected() {

                            // ignore this one..

                // ignore this one… see 5)

            }

            @Override

        @Override

        public void accountAccessGranted(SingleSignOnAccount account) {

            Context l_context = getApplicationContext();

            // As this library supports multiple accounts we created some helper methods if you only want to use one.

            // Get the "default" account

            SingleSignOnAccount ssoAccount = null;

                        try

                        {

            try {

                ssoAccount = SingleAccountHelper.getCurrentSingleSignOnAccount(l_context);

                        } catch (NextcloudFilesAppAccountNotFoundException e)

                        {

                            UiExceptionManager.showDialogForException(l_context, e);

                        } catch (NoCurrentAccountSelectedException e)

                        {

            } catch (NextcloudFilesAppAccountNotFoundException | NoCurrentAccountSelectedException e) {

                UiExceptionManager.showDialogForException(l_context, e);

            }

        NextcloudAPI.ApiConnectedListener callback = new NextcloudAPI.ApiConnectedListener() {

            @Override

            public void onConnected() { 

            // ignore this one..

                // ignore this one… see 5)

            }

            @Override

    AccountImporter.onRequestPermissionsResult(requestCode, permissions, grantResults, this);

}

// Complete example: https://github.com/nextcloud/news-android/blob/master/News-Android-App/src/main/java/de/luhmer/owncloudnewsreader/LoginDialogFragment.java

// Complete example: https://github.com/nextcloud/news-android/blob/890828441ba0c8a9b90afe56f3e08ed63366ece5/News-Android-App/src/main/java/de/luhmer/owncloudnewsreader/LoginDialogActivity.java#L470-L475

```

4) How to get account information?

### 4) How to get account information?

```java

// If you stored the "default" account using setCurrentAccount(...) you can get the account by using the following line:

// If you stored the "default" account using setCurrentAccount(…) you can get the account by using the following line:

SingleSignOnAccount ssoAccount = SingleAccountHelper.getCurrentSingleSignOnAccount(context);

// Otherwise (for multi-account support): (you'll have to keep track of the account names yourself. Note: this has to be the name of SingleSignOnAccount.name)

AccountImporter.getSingleSignOnAccount(context, accountName);

// ssoAccount.name // Name of the account used in the android account manager

// ssoAccount.username

// ssoAccount.token

// ssoAccount.url

ssoAccount.name; // Name of the account used in the android account manager

ssoAccount.username;

ssoAccount.token;

ssoAccount.url;

```

5) How to make a network request?

### 5) How to make a network request?

You'll notice that there is an callback parameter in the constructor of the `NextcloudAPI`.

public NextcloudAPI(Context context, SingleSignOnAccount account, Gson gson, ApiConnectedListener callback) {

```

You can use this callback to subscribe to errors that might occur during the initialization of the API. You can start making requests to the API as soon as you instantiated the `NextcloudAPI` object. For a minimal example to get started (without retrofit) take a look at section 5.2. The callback method `onConnected` will be called once the connection to the files app is established. You can start making calls to the api before that callback is fired as the library will queue your calls until the connection is established.

   5.1) **Using Retrofit**

#### 5.1) **Using Retrofit**

   5.1.1) Before using this single sign on library, your interface for your retrofit API might look like this:

##### 5.1.1) Before using this single sign on library, your interface for your retrofit API might look like this:

```java

public interface API {

    @DELETE("feeds/{feedId}")

    Completable deleteFeed(@Path("feedId") long feedId);

        …

    // …

}

```

}

```

   5.1.2) Use of new API using the nextcloud app network stack

##### 5.1.2) Use of new API using the nextcloud app network stack

```java

public class ApiProvider {

       SingleSignOnAccount ssoAccount = SingleAccountHelper.getCurrentSingleSignOnAccount(context);

       NextcloudAPI nextcloudAPI = new NextcloudAPI(context, ssoAccount, new GsonBuilder().create(), callback);

       mApi = new NextcloudRetrofitApiBuilder(nextcloudAPI, API.mApiEndpoint).create(API.class);

   }

}

```

Note: If you need a different mapping between your json-structure and your java-structure you might want to create a custom type adapter using `new GsonBuilder().create().registerTypeAdapter(...)`. Take a look at [this](https://github.com/nextcloud/news-android/blob/783836390b4c27aba285bad1441b53154df16685/News-Android-App/src/main/java/de/luhmer/owncloudnewsreader/helper/GsonConfig.java) example for more information.

   5.2) **Without Retrofit**

#### 5.2) **Without Retrofit**

`NextcloudAPI` provides a method called `performNetworkRequest(NextcloudRequest request)` that allows you to handle the server response yourself.

                    downloadFile();

                }

            }.start();

            } catch (NextcloudFilesAppAccountNotFoundException e) {

                // TODO handle errors

            } catch (NoCurrentAccountSelectedException e) {

        } catch (NextcloudFilesAppAccountNotFoundException | NoCurrentAccountSelectedException e) {

            // TODO handle errors

        }

    }

    private NextcloudAPI.ApiConnectedListener apiCallback = new NextcloudAPI.ApiConnectedListener() {

        @Override

        public void onConnected() {

                // ignore this one..

            // ignore this one… see 5)

        }

        @Override

    - [Login](https://github.com/stefan-niedermann/nextcloud-notes/blob/master/app/src/main/java/it/niedermann/owncloud/notes/util/SSOUtil.java#L31)

- [Nextcloud Deck app](https://github.com/stefan-niedermann/nextcloud-deck/)

    - [API](https://github.com/stefan-niedermann/nextcloud-deck/blob/master/app/src/main/java/it/niedermann/nextcloud/deck/api/DeckAPI.java)

    - [Login](https://github.com/stefan-niedermann/nextcloud-deck/blob/master/app/src/main/java/it/niedermann/nextcloud/deck/ui/DrawerActivity.java#L288) 

    - [Login](https://github.com/stefan-niedermann/nextcloud-deck/blob/master/app/src/main/java/it/niedermann/nextcloud/deck/ui/ImportAccountActivity.java#L76)

Note that the "Make network request" section in the diagram only shows the workflow if you use the "retrofit" api.

![](doc/NextcloudSingleSignOn.png)

![Flow Diagram](doc/NextcloudSingleSignOn.png)

# Translations

We manage translations via [Transifex](https://www.transifex.com/nextcloud/nextcloud/android-singlesignon/). So just request joining the translation team for Android on the site and start translating. All translations will then be automatically pushed to this repository, there is no need for any pull request for translations.