Android SDK

Device Connect Android SDK is used to collect anonymised non-PII data from the devices of the users after taking explicit user consent.

Requirements#

Device Connect Android SDK works on Android 5.0+ (API level 21+), on Java 8+ and AndroidX. In addition to the changes, enable desugaring to support older versions.

android {
...
defaultConfig {
...
// Minimum 5.0+ devices
minSdkVersion(21)
...
}
...
compileOptions {
// Flag to enable support for the new language APIs
coreLibraryDesugaringEnabled = true
// Sets Java compatibility to Java 8
sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8
}
// For Kotlin projects
kotlinOptions {
jvmTarget = "1.8"
}
}
dependencies {
coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.1.5")
}

Adding Dependency#

In the project level build.gradle file, add the repository URLs to all allprojects block.

maven {
setUrl("s3://risk-manager-android-sdk/artifacts")
credentials(AwsCredentials::class) {
accessKey = <ACCESS_KEY>
secretKey = <SECRET_KEY>
}
content {
includeGroup("in.finbox")
}
}

Now add the dependency to module level build.gradle.kts or build.gradle file:

implementation("in.finbox:mobileriskmanager:<DC_SDK_VERSION>:parent-release@aar") {
isTransitive = true
}
implementation("in.finbox:common:<COMMON_SDK_VERSION>:<COMMON_FLAVOR>-release@aar") {
isTransitive = true
}
implementation("in.finbox:logger:<LOGGER_SDK_VERSION>:parent-release@aar") {
isTransitive = true
}
NOTE

Following will be shared by FinBox team at the time of integration:

  • ACCESS_KEY
  • SECRET_KEY
  • DC_SDK_VERSION
  • COMMON_SDK_VERSION
  • COMMON_FLAVOR
  • LOGGER_SDK_VERSION
  • CLIENT_API_KEY

Create User#

Call createUser method to create the user. It takes Client Api Key and Customer Id as the arguments.

IMPORTANT

Please make sure CUSTOMER_ID is not more than 64 characters and is alphanumeric (with no special characters). Also it should never null or a blank string "".

The response to this method (success or failure) can be captured using the callback FinBoxAuthCallback.

FinBox.createUser("CLIENT_API_KEY", "CUSTOMER_ID",
object : FinBox.FinBoxAuthCallback {
override fun onSuccess(accessToken: String) {
// Authentication is success
}
override fun onError(@FinBoxErrorCode errorCode: Int) {
// Authentication failed
}
})

You can read about the errors in the Error Codes section.

Start Periodic Sync#

This is to be called only on a successful response to createUser method's callback. On calling this the syncs will start for all the data sources configured as per permissions. The method below syncs data in the background at regular intervals:

val finbox = FinBox()
finbox.startPeriodicSync()

Match Details on Device#

Device matching enables additional pattern recognition to match email, phone numbers and name. The matching happens on the device and the user phone numbers, email addresses won't leave the device.

Create the builder by passing email address, phone number and name of the customer.

val deviceMatch = DeviceMatch.Builder().apply {
setEmail("useremail@gmail.com")
setPhone("User Name")
setName("9999999999")
}.build()

Once the in-device values are set, call setDeviceMatch before starting the syncs.

finBox.setDeviceMatch(deviceMatch)
TIP

For Device Match to work at full potential, the SDK expects android.permission.READ_CONTACTS, android.permission.GET_ACCOUNTS, android.permission.READ_SMS to be accepted by the user.

Forward Notifications to SDK#

In certain cases, FinBox server often requests critical data from SDK directly (other than scheduled sync period), to make sure this works it is required to forward FCM Notifications to SDK.

Add the following lines inside the overridden onMessageReceived method available in the service that extends FirebaseMessagingService.

if (MessagingService.forwardToFinBoxSDK(remoteMessage.data)) {
val firebaseMessagingService = MessagingService()
firebaseMessagingService.attachContext(this)
firebaseMessagingService.onMessageReceived(remoteMessage)
} else {
// Rest of your FCM logic
}

Multi-Process Support#

DeviceConnect uses a content provider to auto initialize the SDK. The limitation with the OS is that content providers are only initialized once in a multi-process application and from the main process. For this reason, any calls to the SDK from other processes will lead to unstable behavior.

In case, you want to use the SDK from a process other than the main process, follow the two steps mentioned below to initialize the SDK.

Remove the Content Provider#

Remove the content provider that auto initializes the SDK from the Android Manifest file.

<provider
android:name="in.finbox.mobileriskmanager.init.AutoInitProvider"
android:authorities="in.finbox.lenderapplication.riskmanagerprovider"
android:enabled="true"
android:exported="false"
tools:node="remove" />

Initialize the SDK#

Initialize the FinBox SDK in the onCreate method of Application class.

FinBox.initLibrary(this)

Cancel Periodic Syncing#

If you have already set up the sync for the user data, you can cancel it any time by the following code:

finbox.stopPeriodicSync()

Handle Sync Frequency#

By default sync frequency is set to 8 hours, you can modify it by passing preferred time in seconds as an argument to setSyncFrequency method once the user is created.

Reset User Data#

In case the user data needs to be removed to re-sync the entire data, use the method resetData.

finbox.resetData()

Contents