Skip to content

Accounts SDK for Android

The Accounts SDK is a solution to ease the integration with the Alviere services.

Features

  • Account Management
  • Account Addresses Management
  • Account Dossiers Management

Requirements

  • Android Studio Ladybug or above
  • Android 7.0 (API level 24) or above
  • Java 11+

Installation

Maven Central

1. Add Maven Central to project repositories

repositories {
    // ...
    mavenCentral()
}

2. Add SDK dependency to module's build.gradle file using the latest version.

dependencies {
    // ...
    implementation 'com.alviere.android:accounts:X.Y.Z'
}

Manual

1. Get the latest version of Accounts SDK provided by Alviere and add the files to your .m2 path location. Depending on your operation system, these are the default paths.

  • Windows: C:\Users\<User_Name>\.m2
  • Linux: /home/<User_Name>/.m2
  • Mac: /Users/<user_name>/.m2

2. Add a maven path to include the .m2 path location in project repositories. Add the new path before mavenCentral() to respect fetch order.

repositories {
    // ...
    maven { url "file:/path/to/repo/m2repository/" } // Or use mavenLocal() for default path.
    mavenCentral()
}

3. Add SDK dependency to module's build.gradle file using the version provided by Alviere.

dependencies {
    // ...
    implementation 'com.alviere.android:accounts:X.Y.Z'
}

Java Version Support

Make sure you have enabled Java 11 language feature support. To do so, guarantee that the following configurations are on the module's build.gradle file.

android {
    // ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_11.toString()
    }
}

Usage

On your android application class, setup Alviere Initialization.

class AndroidApplication : Application() {

  override fun onCreate() {
    super.onCreate()

    Alviere.init(this, EnvironmentOption.SND)
  }
}

Request camera runtime permission for document capture.

ActivityCompat.requestPermissions(..., arrayOf(Manifest.permission.CAMERA),...)

Account Management

This section outlines the integration with Alviere to manage accounts. To Start get the AccountsSdk service interface instance or use with Dependency Injection.

private val accountsService = AccountsSdk.service

Coroutine Usage

Every SDK entry function without UI is a suspend function to run inside a kotlin coroutine. Internal code will run with withContext(Dispatchers.IO) and will return an object of type Response<T>.

val response = accountsService.request(...)
when (response) {
  is Response.Success -> { response.data }
  is Response.Error -> { response.metadata }
}

Callback Usage

For every suspend function there is a callback function. UI functions will always work only thru callbacks and callbacks will always run on the main thread. Callbacks Source

List Accounts

To obtain a list of accounts, use the Accounts SDK service method accountsService.listAccounts. Pass the session_token, the parent_account_uuid and the limit/offset/startDate/endDate/type/type/status/stage, optionally.

accountsService.listAccounts(
    sessionToken = session_token,
    parentAccountUuid = parent_account_uuid,
)

The result of this action will return the specific List<AccountDetailsModel> on Response.Success and any errors will be returned on Response.Error.

Get Account

To obtain an account, use the Accounts SDK service method accountsService.getAccount. Pass the session_token and the account_uuid.

accountsService.getAccount(
    sessionToken = session_token,
    accountUuid = account_uuid,
)

The result of this action will return the specific AccountDetailsModel on Response.Success and any errors will be returned on Response.Error.

Update Account

To update an account, use the Accounts SDK service method accountsService.updateAccount. Pass the session_token, the account_uuid and the AccountUpdateRequest model.

val model = AccountUpdateRequest(...)
accountsService.updateAccount(
    sessionToken = session_token,
    accountUuid = account_uuid,
    data = model,
)

The result of this action will return the updated AccountDetailsModel on Response.Success and any errors will be returned on Response.Error.

Account Addresses Management

This section outlines the integration with Alviere to manage account addresses. To Start get the AccountsSdk service interface instance or use with Dependency Injection.

private val accountsService = AccountsSdk.service

Coroutine Usage

Every SDK entry function without UI is a suspend function to run inside a kotlin coroutine. Internal code will run with withContext(Dispatchers.IO) and will return an object of type Response<T>.

val response = accountsService.request(...)
when (response) {
  is Response.Success -> { response.data }
  is Response.Error -> { response.metadata }
}

Callback Usage

For every suspend function there is a callback function. UI functions will always work only thru callbacks and callbacks will always run on the main thread. Callbacks Source

Create Address

To add an account address, use the Accounts SDK service method accountsService.createAddress. Pass the session_token, the account_uuid and the AddressRequest model.

val model = AddressRequest(...)
accountsService.createAddress(
    sessionToken = session_token,
    accountUuid = account_uuid,
    data = model,
)

The result of this action will return the newly created AddressDetailsModel on Response.Success and any errors will be returned on Response.Error.

List Addresses

To get a list of addresses from an account, use the Accounts SDK service method accountsService.listAddresses. Pass the session_token and the account_uuid.

accountsService.listAddresses(
    sessionToken = session_token,
    accountUuid = account_uuid,
)

The result of this action will return the account's addresses List<AddressDetailsModel> on Response.Success and any errors will be returned on Response.Error.

Update Address

To update an account address, use the Accounts SDK service method accountsService.updateAddress. Pass the session_token, the account_uuid, the address_uuid and the AddressUpdateRequest model.

val model = AddressUpdateRequest(...)
accountsService.updateAddress(
    sessionToken = session_token,
    accountUuid = account_uuid,
    addressUuid = address_uuid,
    data = model,
)

The result of this action will return the updated AddressDetailsModel on Response.Success and any errors will be returned on Response.Error.

Delete Address

To delete an account address, use the Accounts SDK service method accountsService.deleteAddress. Pass the session_token, the account_uuid and the address_uuid.

accountsService.deleteAddress(
    sessionToken = session_token,
    accountUuid = account_uuid,
    addressUuid = address_uuid,
)

The result of this action will return on Response.Success and any errors will be returned on Response.Error.

Account Dossiers Management

This section outlines the integration with Alviere to manage dossiers of documents. To start, get the AccountsSdk service interface instance or use with Dependency Injection.

private val accountsService = AccountsSdk.service
private val tokenRepository = TokenRepository()

Coroutine Usage

Every SDK entry function without UI is a suspend function to run inside a kotlin coroutine. Internal code will run with withContext(Dispatchers.IO) and will return an object of type Response<T>.

val response = accountsService.request(...)
when (response) {
  is Response.Success -> { response.data }
  is Response.Error -> { response.metadata }
}

Callback Usage

For every suspend function there is a callback function. UI functions will always work only thru callbacks and callbacks will always run on the main thread. Callbacks Source

Dossier UI Callback

The Create, Update or Replace a Dossier of Documents, a Capture Mode through Compose or through Compose from an activity. To get started, set the Accounts SDK event listener and obtain a camera token.

AccountsSdk.setEventListener(dossierUploadSdkCallback)
tokenRepository.getCameraToken(...)

[UI] Create Dossier

Compose

To start using this feature with Compose, wrap CreateDossierScreen inside a typical navigation composable, pass the list of documents to capture using DocumentTypeModel with a selection of different document types, the camera_token, the session_token, the external_id, the account_uuid, the primary_dossier, the real_time_verification, the country_of_issuance and the action to close the view.

CreateDossierScreen(
  documentsToCapture = listOf(
    DocumentTypeModel.DRIVER_LICENSE_FRONT,
    DocumentTypeModel.DRIVER_LICENSE_BACK,
    DocumentTypeModel.SELFIE,
  ),
  cameraToken = camera_token,
  sessionToken = session_token,
  externalId = external_id,
  accountUuid = account_uuid,
  primary = primary_dossier,
  realTimeVerification = real_time_verification,
  countryOfIssuance = country_of_issuance,
  onCloseAction = navController::navigateUp,
)

Compose From Activity

To start using this feature with Compose from an activity, create a new activity and set the composable content CreateDossierScreen inside onCreate, pass the list of documents to capture using DocumentTypeModel with a selection of different document types, the camera_token, the session_token, the external_id, the account_uuid, the primary_dossier, the real_time_verification, the country_of_issuance and the action to close the view.

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  setContent {
    MaterialTheme {
      CreateDossierScreen(
        documentsToCapture = listOf(
          DocumentTypeModel.DRIVER_LICENSE_FRONT,
          DocumentTypeModel.DRIVER_LICENSE_BACK,
          DocumentTypeModel.SELFIE,
        ),
        cameraToken = camera_token,
        sessionToken = session_token,
        externalId = external_id,
        accountUuid = account_uuid,
        primary = primary_dossier,
        realTimeVerification = real_time_verification,
        countryOfIssuance = country_of_issuance,
        onCloseAction = ::finish,
      )
    }
  }
}

The result of this actions will return the specific DossierDetailsModel on onCreateSuccess(dossier: DossierDetailsModel) and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

Create Dossier

To create an user account dossier of documents, use the Accounts SDK service method accountsService.createDossier. Pass the session_token, the external_id, the account_uuid, the primary, the real_time_verification, the country_of_issuance and the filesToSend from DocumentCaptureScreen.

accountsService.createDossier(
    sessionToken = session_token,
    externalId = external_id,
    accountUuid = account_uuid,
    primary = primary,
    realTimeVerification = real_time_verification,
    countryOfIssuance = country_of_issuance,
    filesToSend = filesToSend,
)

The result of this action will return the specific DossierDetailsModel on Response.Success and any errors will be returned on Response.Error.

[UI] Update Dossier

Compose

To start using this feature with Compose, wrap UpdateDossierScreen inside a typical navigation composable, pass the list of documents to capture using DocumentTypeModel with a selection of different document types, the camera_token, the session_token, the external_id, the account_uuid, the dossier_uuid, the real_time_verification, the country_of_issuance and the action to close the view.

UpdateDossierScreen(
  documentsToCapture = listOf(
    DocumentTypeModel.DRIVER_LICENSE_FRONT,
    DocumentTypeModel.DRIVER_LICENSE_BACK,
    DocumentTypeModel.SELFIE,
  ),
  cameraToken = camera_token,
  sessionToken = session_token,
  externalId = external_id,
  accountUuid = account_uuid,
  dossierUuid = dossier_uuid,
  realTimeVerification = real_time_verification,
  countryOfIssuance = country_of_issuance,
  onCloseAction = navController::navigateUp,
)

Compose From Activity

To start using this feature with Compose from an activity, create a new activity and set the composable content UpdateDossierScreen inside onCreate, pass the list of documents to capture using DocumentTypeModel with a selection of different document types, the camera_token, the session_token, the external_id, the account_uuid, the dossier_uuid, the real_time_verification, the country_of_issuance and the action to close the view.

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  setContent {
    MaterialTheme {
      UpdateDossierScreen(
        documentsToCapture = listOf(
          DocumentTypeModel.DRIVER_LICENSE_FRONT,
          DocumentTypeModel.DRIVER_LICENSE_BACK,
          DocumentTypeModel.SELFIE,
        ),
        cameraToken = camera_token,
        sessionToken = session_token,
        externalId = external_id,
        accountUuid = account_uuid,
        dossierUuid = dossier_uuid,
        realTimeVerification = real_time_verification,
        countryOfIssuance = country_of_issuance,
        onCloseAction = ::finish,
      )
    }
  }
}

The result of this actions will return the specific DossierDetailsModel on onUpdateSuccess(dossier: DossierDetailsModel) and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

Update Dossier

To update an user account dossier of documents, use the Accounts SDK service method accountsService.updateDossier. Pass the session_token, the external_id, the account_uuid, the dossier_uuid, the real_time_verification, the country_of_issuance and the filesToSend from DocumentCaptureScreen.

accountsService.updateDossier(
  sessionToken = session_token,
  externalId = external_id,
  accountUuid = account_uuid,
  dossierUuid = dossier_uuid,
  realTimeVerification = real_time_verification,
  countryOfIssuance = country_of_issuance,
  filesToSend = filesToSend,
)

The result of this action will return the specific DossierDetailsModel on Response.Success and any errors will be returned on Response.Error.

[UI] Replace Dossier

Compose

To start using this feature with Compose, wrap ReplaceDossierScreen inside a typical navigation composable, pass the list of documents to capture using DocumentTypeModel with a selection of different document types, the camera_token, the session_token, the external_id, the account_uuid, the dossier_uuid, the real_time_verification, the country_of_issuance and the action to close the view.

ReplaceDossierScreen(
  documentsToCapture = listOf(
    DocumentTypeModel.DRIVER_LICENSE_FRONT,
    DocumentTypeModel.DRIVER_LICENSE_BACK,
    DocumentTypeModel.SELFIE,
  ),
  cameraToken = camera_token,
  sessionToken = session_token,
  externalId = external_id,
  accountUuid = account_uuid,
  dossierUuid = dossier_uuid,
  realTimeVerification = real_time_verification,
  countryOfIssuance = country_of_issuance,
  onCloseAction = navController::navigateUp,
)

Compose From Activity

To start using this feature with Compose from an activity, create a new activity and set the composable content ReplaceDossierScreen inside onCreate, pass the list of documents to capture using DocumentTypeModel with a selection of different document types, the camera_token, the session_token, the external_id, the account_uuid, the dossier_uuid, the real_time_verification, the country_of_issuance and the action to close the view.

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  setContent {
    MaterialTheme {
      ReplaceDossierScreen(
        documentsToCapture = listOf(
          DocumentTypeModel.DRIVER_LICENSE_FRONT,
          DocumentTypeModel.DRIVER_LICENSE_BACK,
          DocumentTypeModel.SELFIE,
        ),
        cameraToken = camera_token,
        sessionToken = session_token,
        externalId = external_id,
        accountUuid = account_uuid,
        dossierUuid = dossier_uuid,
        realTimeVerification = real_time_verification,
        countryOfIssuance = country_of_issuance,
        onCloseAction = ::finish,
      )
    }
  }
}

The result of this actions will return the specific DossierDetailsModel on onReplaceSuccess(dossier: DossierDetailsModel) and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

Replace Dossier

To replace an user account dossier of documents, use the Accounts SDK service method accountsService.replaceDossier. Pass the session_token, the account_uuid, the dossier_uuid, the real_time_verification, the country_of_issuance and the filesToSend from DocumentCaptureScreen.

accountsService.replaceDossier(
  sessionToken = session_token,
  accountUuid = account_uuid,
  dossierUuid = dossier_uuid,
  realTimeVerification = real_time_verification,
  countryOfIssuance = country_of_issuance,
  filesToSend = filesToSend,
)

The result of this action will return the specific DossierDetailsModel on Response.Success and any errors will be returned on Response.Error.

List Dossiers

To obtain an user account dossiers of documents, use the Accounts SDK service method accountsService.listDossiers. Pass the session_token and the account_uuid.

accountsService.listDossiers(
    sessionToken = session_token,
    accountUuid = account_uuid,
)

The result of this action will return the specific List<DossierDetailsModel> on Response.Success and any errors will be returned on Response.Error.

Get Dossier

To obtain an user account dossier of documents, use the Accounts SDK service method accountsService.getDossier. Pass the session_token, the account_uuid and the dossier_uuid.

accountsService.getDossier(
    sessionToken = session_token,
    accountUuid = account_uuid,
    dossierUuid = dossier_uuid,
)

The result of this action will return the specific DossierDetailsModel on Response.Success and any errors will be returned on Response.Error.

Delete Dossier

To delete an user account dossier of documents, use the Accounts SDK service method accountsService.deleteDossier. Pass the session_token, the account_uuid and the dossier_uuid.

accountsService.deleteDossier(
    sessionToken = session_token,
    accountUuid = account_uuid,
    documentId = dossier_uuid,
)

The result of this action will return on Response.Success and any errors will be returned on Response.Error.

[UI] Document Capture Only

Document Capture Only, a Capture Mode through Compose or through Compose from an activity. To get started, set the Accounts SDK event listener.

AccountsSdk.setEventListener(documentCaptureSdkCallback)

Compose

To start using this feature with Compose, wrap DocumentCaptureScreen inside a typical navigation composable, pass the list of documents to capture using DocumentTypeModel with a selection of different document types, the camera_token and the action to close the view.

DocumentCaptureScreen(
  documentsToCapture = listOf(
    DocumentTypeModel.DRIVER_LICENSE_FRONT,
    DocumentTypeModel.DRIVER_LICENSE_BACK,
    DocumentTypeModel.SELFIE,
  ),
  cameraToken = camera_token,
  onCloseAction = navController::navigateUp,
)

Compose From Activity

To start using this feature with Compose from an activity, create a new activity and set the composable content DocumentCaptureScreen inside onCreate, pass the list of documents to capture using DocumentTypeModel with a selection of different document types, the camera_token and the action to close the view.

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  setContent {
    MaterialTheme {
      DocumentCaptureScreen(
        documentsToCapture = listOf(
          DocumentTypeModel.DRIVER_LICENSE_FRONT,
          DocumentTypeModel.DRIVER_LICENSE_BACK,
          DocumentTypeModel.SELFIE,
        ),
        cameraToken = camera_token,
        onCloseAction = ::finish,
      )
    }
  }
}

The result of this actions will return the specific List<DocumentCaptureDetailsModel> on onSuccess(documents: List<DocumentCaptureDetailsModel>) and any errors will be returned on onEvent(event: String, metadata: Map<String, String>?), both from the callback.

Fraud Prevention Service

The Accounts SDK has a built-in fraud prevention service. To fully enable the service you need to setup by calling FraudDetection.initFraudDetection(application)

class AppApplication : Application() {

  override fun onCreate() {
    // ...
    FraudDetection.initFraudDetection(this)
    // ...
  }
}

If you already have an account created and want to activate the service on the next app run you just need to set the accountUuid on the service as the user id. For example, you can do this on calling FraudDetection.setFraudUserId(account_uuid) method, as shown below.

private suspend fun xpto(): Response<_> {
  return try {
    when (val resource = alviereRepo.createUser(...)) {
      is Resource.Success -> {
        // ...
        FraudDetection.setFraudUserId(result.account.accountUuid)
      }
      is Resource.Error -> Response.Error(...)
    }
  } catch (e: Throwable) {
    // ...
  }
}

Customization Object

To start, create a AccountsCustomize object and set it by AccountsSdk.setCustomize.

This object has a default customizations for every UI feature of the SDK. Navigate through the object source code to check all possible configurations and change any value.

val customize = AccountsCustomize(
  documentsCaptureCustomize = DocumentsCaptureCustomize(
    idDocumentFrontTitle = R.string.title_id_document_front,
    titleTextStyle = alviereTitleXLRegular.copy(
      fontSize = 20.sp,
    )
  ),
)

AccountsSdk.setCustomize(customize)

Text and Localization

The AccountsCustomize by default uses String Resources from strings.xml. This allows string keys to be override directly in your string resources file and new languages can be added. Currently, the SDK only supports english.

Fonts

The AccountsCustomize uses Compose TextStyle for every text configuration and this includes font family. Currently, the default value is FontFamily.SansSerif.

Customization Theme

The Accounts SDK uses a color schema AccountsSdkColors to customize the Colors of every UI feature and this allows a more robust implementation on top of MaterialTheme, including light and dark mode.

By default, the Accounts SDK uses a default light mode color schema, but you can configure dark mode, or use a custom color schema AccountsSdkColors as explained below.

@Composable
fun AppTheme(
  darkTheme: Boolean = isSystemInDarkTheme(),
  content: @Composable () -> Unit,
) {
  val colorScheme = if (darkTheme) darkScheme else lightScheme
  val accountsSdkColors = if (darkTheme) darkAccountsSdkColorPalette else lightAccountsSdkColorPalette

  CompositionLocalProvider(
    LocalAccountsSdkColorPalette provides accountsSdkColors,
  ) {
    MaterialTheme(
      colorScheme = colorScheme,
      content = content,
    )
  }
}

The lightAccountsSdkColorPalette and darkAccountsSdkColorPalette can be recreated by using the same functions and changing the default colors.

val accountsSdkColors = if (darkTheme) {
  AccountsSdkColors(
    documentCaptureTokens = accountsDocumentCaptureDarkColors(
      captureBackground = Color.Black,
    ),
  )
} else {
  AccountsSdkColors(
    documentCaptureTokens = accountsDocumentCaptureLightColors(
      captureBackground = Color.Black,
    ),
  )
}