auth

Version: 1.1.0

Contains authentication functions used in the anybill sdk.

Having problems? Contact us at <dev@anybill.de>

Release History

  • 1.1.0

    • Reset version number on Artifactory Move

Resolving the artifact using gradle:

Add this to your project's build.gradle with:

allprojects {
    repositories {
        maven {
            url "https://anybill.jfrog.io/artifactory/anybill_android_sdk"
            credentials {
                username = {username}
                password = {password}
            }
        }
        //Datadog is used for internal logging in anybill sdk.
        maven {
            url "https://dl.bintray.com/datadog/datadog-maven"
        }
    }
}

Add this to your module's build.gradle:

dependencies {
    implementation 'de.anybill.anybill_android_sdk:auth:{latest version}'
}

Resolving the artifact using maven:

Add this to your settings.xml:

<?xml version="1.0" encoding="UTF-8"?>
<settings 
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd" 
    xmlns="http://maven.apache.org/SETTINGS/1.1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <servers>
    <server>
      <username>${security.getCurrentUsername()}</username>
      <password>${security.getEscapedEncryptedPassword()!"*** Insert encrypted password here ***"}</password>
      <id>central</id>
    </server>
    <server>
      <username>${security.getCurrentUsername()}</username>
      <password>${security.getEscapedEncryptedPassword()!"*** Insert encrypted password here ***"}</password>
      <id>snapshots</id>
    </server>
  </servers>
  <profiles>
    <profile>
      <repositories>
        <repository>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
          <id>central</id>
          <name>maven-release</name>
          <url>https://anybill.jfrog.io/artifactory/maven-release</url>
        </repository>
        <repository>
          <snapshots />
          <id>snapshots</id>
          <name>maven-release</name>
          <url>https://anybill.jfrog.io/artifactory/maven-release</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
          <id>central</id>
          <name>maven-release</name>
          <url>https://anybill.jfrog.io/artifactory/maven-release</url>
        </pluginRepository>
        <pluginRepository>
          <snapshots />
          <id>snapshots</id>
          <name>maven-release</name>
          <url>https://anybill.jfrog.io/artifactory/maven-release</url>
        </pluginRepository>
      </pluginRepositories>
      <id>artifactory</id>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>artifactory</activeProfile>
  </activeProfiles>
</settings>

Add this dependency:

<dependency>
	<groupId>de.anybill.anybill_android_sdk</groupId>
	<artifactId>auth</artifactId>
	<version>{latest version}</version>
	<type>pom</type>
</dependency>

Required modules

The authentication module depends on the following anybill SDK modules and can't be used without them:

:core
:log

The authentication module is part of the SDK's core functions which consists of the following SDK modules:

:core
:bill
:auth
:category   
:log

Please add the corresponding dependencies to your module's build.gradle.

Coming soon: Single dependency for the SDK's core functions.

Usage

Error Handling

The anybill sdk uses a custom error handling model. All methods return a type of the sealed class ApiResult, including the return object on success and/or information about the error which occurred. Detailed description of the possible error codes can be found in the corresponding documentation of the methods

sealed class ApiResult<out T> {

    /**
     * Success\
     * Used when Api Call and serialization was successful\
     *
     * @param T Type [T] of the object which should be returned if Api call and JSON Serialization was successful
     * @property value Object of type [T] holding the serialized result of the api call
     */

    data class Success<out T>(val value: T) : ApiResult<T>()

    /**
     * Generic error\
     * Used if a generic error occurs during execution of the api call or serialization of the received data\
     * Possible GenericError's of each operation are listed in the method documentation
     *
     * @property code Nullable [Int] with the Error Code of the exception
     * @property error Nullable [ErrorResponse] object with further exception information
     */

    data class GenericError(val code: Int? = null, val error: ErrorResponse? = null) : ApiResult<Nothing>()

    /**
     * Empty success\
     * Used if the execution of the api call and the serialization of the result was successful without a need of a result object (e.g. token operations)\
     *
     */

    object EmptySuccess : ApiResult<Nothing>()

    /**
     * Network error\
     * Used if a network error occurs during execution of the api call (e.g. timeout, no network)
     */

    object NetworkError : ApiResult<Nothing>()
}

Example usage of the error model based on the user info task of the AuthProvider.

fun getUserInfo() {
        viewModelScope.launch {
            when (val userInfoTask = AuthProvider.getUserInfo()) {
                is NetworkError -> //Error Handling
                is GenericError -> {
                    when(userInfoTask.code){
                        NO_USER -> //Error Handling
                        NOT_SYNCABLE -> //Error Handling
                        SERVER_ERROR -> //Error Handling
                        REFRESH_ERROR -> //Error Handling
                    }       
                }
                is Success -> {
                    userInfoTask.value //Further implementation
                }
            }
        }
    }

Example usage of the public provider and models:

Providers

AuthProvider

Singleton provider granting access to the anybill authentication functionalities. Most functions of the AuthProvider are suspend functions and have to be called in a coroutine scope.

Login

To login an user you can choose between logging in an anybill user, an anonymous user or use your own authentication token (token user).

Anybill user

Anybill users can be logged in using the loginUser() method of the AuthProvider. It requires valid login information of a registered anybill user (email and password).

    fun loginUser(email: String, password: String) {
        viewModelScope.launch {
           AuthProvider.loginUser(email = email, password = password)             
        }
    }

Anonymous user

By using this functionality the SDK creates a anonymous user account in the background with no email or password. With this authentication method the user can use the anybill services (with certain restrictions) as if he had no user account. The anonymous user account can be converted to a normal anybill account with email and password later on.

    fun loginAnonymousUser() {
        viewModelScope.launch {
            AuthProvider.createAnonymousUser()
        }
    }

After an App or its data gets deleted, the anonymous account cannot be restored because there is no reference to the old account left.

Linked token user

If your App has an own user account system you can link an anybill user to your user account by using the linked token user:

  • Get a token from the anybill Partner API by linking you account system to an anybill id.

  • Create an instance of TokenUser with the received token-information

  • Login the TokenUser with the anybill sdk

    fun loginTokenUser(tokenUser: TokenUser){
        AuthProvider.loginTokenUser(tokenUser)
    }

Further information about the login possibilities can be found on the anybill developer page.

Register

To register a new anybill user use the registerUser() method. It requires a valid email, a password which fulfills anybill's password policy (at least 8 characters with 1 lowercase, 1 capital letters and 1 number) and the first name of the user. Other information of the user is optional. By setting autoLogin to true the user is going to be automatically logged in after a successful registration (default = false).

    fun registerUser(email: String, password: String, firstName: String) {
        viewModelScope.launch {
            val anybillUser = AuthProvider.registerUser(email, password, firstName, autoLogin = true)
        }
    }

Converting an anonymous user to an anybill User. Anonymous users have restricted access to the anybill functions (e.g. restricted amount of bills). If the app user wants to take use of all the anybill functions he has to create an anybill account. To retain the data of an anonymous user the anybill sdk provides a function to convert an anonymous user to an anybill user. 

    fun convertAnonymousUser(email: String, password: String, firstName: String, gender: String) {
        viewModelScope.launch {
            AuthProvider.convertAnonymousUserToAnybillUser(email, password, firstName, gender)
        }
    }

Afterwards the user can login into his anybill account using his login credentials.

Get QR Code Data

Certain points of sale allow anybill users to receive bills by scanning a QR code on the user's phone. To get the jsonObject which should be included in the QR Code use the getQRCodeDatamethod.

    viewModelScope.launch {
        AuthProvider.getQRCodeData())
    }

More information about QR Code data can be found on the anybill developer page.

Logout

Logging out an user deletes all of user's app data including cached bills, authentication information and app settings (of the anybill sdk).

    AuthProvider.logoutUser()

Delete Account

Deleting an anybill account is irreversibly. The account can not be retrieved afterwards.

    fun deleteUser() {
        viewModelScope.launch {
            anybillAuth.deleteCurrentUser()
        }
    }

TokenProvider

The TokenProvider is used for internal authentication operations. The public methods should not be accessed from the app itself. It might cause problem during the anybill authentication process.

Models

AnybillUser

Data class representing a registered AnybillUser

data class AnybillUser(
    val id: String,
    val email: String,
    val firstName: String,
    val lastName: String?,
    val birthday: String?,
    val gender: String?
)

TokenUser

Data class model representing the token information of an token user

data class TokenUser(
    val accessToken: String,
    val refreshToken: String,
    val expiresIn: String
)

Detailed description of the structure and function of models/variables can be found in the code or provided KDoc.

Packages