From 1017a06d9e17f77c980c199f0eda64c171ad3509 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CMithali=E2=80=9D?=
<“mithali.parwatkar@finbox.in”>
Date: Fri, 4 Apr 2025 14:51:42 +0530
Subject: [PATCH 1/8] revised the requirements
---
docs/device-connect/android.md | 11 ++++++++++-
1 file changed, 10 insertions(+), 1 deletion(-)
diff --git a/docs/device-connect/android.md b/docs/device-connect/android.md
index a0186ff5..6cb1e887 100644
--- a/docs/device-connect/android.md
+++ b/docs/device-connect/android.md
@@ -8,7 +8,16 @@ The DeviceConnect Android SDK enables the collection of anonymized, non-PII data
## Requirements
-DeviceConnect Android SDK works on Android 5.0+ (API level 21+), on Java 8+ and AndroidX. In addition to the changes, enable desugaring so that our SDK can run smoothly on Android 7.0 and versions below.
+To ensure compatibility and optimal performance of the SDK, the following minimum requirements must be met:
+- **Android OS Version**: Android 5.0 (Lollipop) or higher (API Level 21+)
+- **Java Version**: Java 8 or higher
+- **Support Libraries**: AndroidX libraries are mandatory
+
+::: warning NOTE
+The SDK is built using **Java 8** language features, which are not fully supported on **Android 7.0** and below.
+To maintain compatibility with older devices, it is essential to enable Java 8 desugaring in your project.
+Devices running Android 8.0 (API 26) and above do not require desugaring, as Java 8 support is natively available.
+:::
From 59e614e52a4d69c9299f6a047f22ebd5d794fe7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CMithali=E2=80=9D?=
<“mithali.parwatkar@finbox.in”>
Date: Fri, 4 Apr 2025 14:54:20 +0530
Subject: [PATCH 2/8] versions made bold
---
docs/device-connect/android.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/device-connect/android.md b/docs/device-connect/android.md
index 6cb1e887..5baa92cc 100644
--- a/docs/device-connect/android.md
+++ b/docs/device-connect/android.md
@@ -15,8 +15,8 @@ To ensure compatibility and optimal performance of the SDK, the following minimu
::: warning NOTE
The SDK is built using **Java 8** language features, which are not fully supported on **Android 7.0** and below.
-To maintain compatibility with older devices, it is essential to enable Java 8 desugaring in your project.
-Devices running Android 8.0 (API 26) and above do not require desugaring, as Java 8 support is natively available.
+To maintain compatibility with older devices, it is essential to **enable Java 8 desugaring** in your project.
+Devices running **Android 8.0** and above **do not require desugaring**, as Java 8 support is natively available.
:::
From daf9c742f5b173bf30d1867706bd04c345e9e6aa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CMithali=E2=80=9D?=
<“mithali.parwatkar@finbox.in”>
Date: Fri, 4 Apr 2025 17:26:54 +0530
Subject: [PATCH 3/8] grammatical revisions to Add dependency
---
docs/device-connect/android.md | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/docs/device-connect/android.md b/docs/device-connect/android.md
index 5baa92cc..b11316d4 100644
--- a/docs/device-connect/android.md
+++ b/docs/device-connect/android.md
@@ -86,7 +86,9 @@ dependencies {
## Add Dependency
-In the project level `build.gradle` file or `settings.gradle`, add the repository URLs to all `allprojects` block or `repositories` block inside `dependencyResolutionManagement`.
+To include the DeviceConnect SDK in your project, configure your repository settings as follows:
+
+In your project-level `build.gradle` or `settings.gradle`, add the FinBox private Maven repository under the `allprojects.repositories` or `dependencyResolutionManagement.repositories` block.
@@ -123,7 +125,7 @@ maven {
-Now add the dependency to module level `build.gradle.kts` or `build.gradle` file:
+In your module-level `build.gradle.kts` or `build.gradle` file, add the required FinBox SDK dependencies
@@ -159,7 +161,7 @@ implementation ('in.finbox:logger::parent-release@aar') {
::: warning NOTE
-Following will be shared by FinBox team at the time of integration:
+The following integration details will be provided by the FinBox team at the time of onboarding:
- `ACCESS_KEY`
- `SECRET_KEY`
From 637640c073e1d64ac23b60803aa71b5f0d4593a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CMithali=E2=80=9D?=
<“mithali.parwatkar@finbox.in”>
Date: Fri, 4 Apr 2025 18:25:44 +0530
Subject: [PATCH 4/8] content changes for createuser, startperiodicsync and in
device match
---
docs/device-connect/android.md | 87 ++++++++++++++++++++++++----------
1 file changed, 63 insertions(+), 24 deletions(-)
diff --git a/docs/device-connect/android.md b/docs/device-connect/android.md
index b11316d4..d12b0de3 100644
--- a/docs/device-connect/android.md
+++ b/docs/device-connect/android.md
@@ -173,21 +173,14 @@ The following integration details will be provided by the FinBox team at the tim
- `CLIENT_API_KEY`
:::
-## Create User
+## User Initialization with `createUser`
-To create a user, call the `createUser` method with the following arguments:
+To begin data collection and syncing, the DeviceConnect SDK requires associating the current app session with a user. This is done using the `createUser` method
-- Client API Key
-- Customer ID
-
-::: danger IMPORTANT
-
-- `CUSTOMER_ID` Must be **alphanumeric** (no special characters).
-- Should not exceed **64** characters.
-- Must not be `null` or an empty string `""`.
-:::
-
-The response (success or failure) is handled using the `FinBoxAuthCallback` callback.
+|:Parameter |:Type |:Description |
+|----------|----------|----------|
+| CLIENT_API_KEY | String| The unique FinBox API key assigned to your application |
+| CUSTOMER_ID | String | Unique identifier assigned to the user by your system (see format rules) |
@@ -226,11 +219,29 @@ FinBox.createUser("CLIENT_API_KEY", "CUSTOMER_ID",
+:warning: **Customer ID Rules**:
+- Must be alphanumeric only (no special characters)
+- Cannot exceed 64 characters
+- Must not be null or an empty string ("")
+
+The response (success or failure) is handled using the `FinBoxAuthCallback` callback.
+
+:repeat: **Behavior Notes**:
+- The method is idempotent: calling it repeatedly with the same customerId will not cause an error.
+- If the customer is already registered, the SDK will return a success response and continue as expected.
+- If invalid credentials or customer ID are provided, onError() is triggered with a specific error code
+
You can read about the errors in the [Error Codes](/device-connect/error-codes.html) section.
-## Start Periodic Sync
+## Starting Background Data Sync: `startPeriodicSync()`
+
+The startPeriodicSync() method begins regular background syncing of user data, based on the permissions granted to the app. It should be called only after a successful `createUser` call.
+
+:gear: **Usage Guidelines**:
+
+- This method must be called only after a successful response from the `createUser` callback.
+- It is essential to ensure that the user has been successfully authenticated and linked to a valid `customerId` before enabling background sync
-The startPeriodicSync method should be invoked only after receiving a successful response from the `createUser` method callback. This method initiates background syncing for all data sources based on the permissions granted by the user. Data is synced at regular intervals in the background, ensuring continuous and seamless data collection.
@@ -252,21 +263,45 @@ finbox.startPeriodicSync();
-::: tip RECOMMENDATION
-To handle cross-login scenarios:
+:repeat: **Functionality Overview**:
+- Initiates periodic background syncing of user data from all enabled sources (e.g., SMS, installed apps etc).
+- Sync intervals are controlled using the `setSyncFrequency` method.
+- Default collection frequency is 8 hrs and this is configurable.
+- Sync operations are optimized for battery and network conditions.
+ - Automatically pauses syncing when the battery is low.
+ - Resumes syncing when the device is charging or reconnected to a network
+
+:lock: **Permissions-Driven Behavior**:
+- Data syncing respects all runtime permissions granted by the user. If any required permission (e.g., SMS, Installed etc) is not granted or is later revoked:
+ - The SDK will skip syncing from that data source.
+ - No crash or exception will be thrown; sync continues from other available sources.
+
+::: tip Handling User Switch or Cross-Login Scenarios
+When a user logs out and another user logs into the same device (e.g., a different customer ID), it’s important to ensure that the SDK cleanly associates the new user with future data syncs.
+
+**Recommended Flow on User Login**:
+Upon login with a new set of credentials:
-When a user logs back into the app with fresh credentials:
+1. Call `createUser()`
+- This links the new customerId with the SDK.
+- The method is idempotent and will handle duplicate calls gracefully if the same user logs in again.
-- Call the `createUser` method to register the new user.
-- Follow it by `startPeriodicSync` to resume data syncing for the new user.
-Even though the SDK automatically adapts to a new user, this approach minimizes potential delays in syncing during the first session
+2. Call `startPeriodicSync()`
+- This resumes background syncing immediately, ensuring minimal delay in starting data collection for the new session.
:::
-## Match Details on Device (Important)
+## :lock: Match Details on Device (Important)
-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.
+Device matching enhances the SDK's ability to associate user identity signals—such as email address, phone number, and name—with behavioral patterns. This improves insight accuracy while maintaining strict privacy boundaries. These values are securely processed on-device and used only for matching purposes.
-Create the builder by passing email address, phone number and name of the customer.
+:brain: **How It Works**:
+- All matching and signal generation are performed locally on the device.
+- No personal information (phone number, email, name) is ever transmitted to FinBox servers.
+
+This mechanism supports deeper validation of user ownership without compromising user privacy.
+
+:wrench: **Implementation**:
+Use the provided builder method to pass the user's identity attributes:
@@ -294,6 +329,10 @@ final DeviceMatch deviceMatch = builder.build();
+::: warning NOTE
+This step is optional but highly recommended for improved insight quality in multi-user or shared-device environments.
+:::
+
Once the in-device values are set, call `setDeviceMatch` before starting the syncs.
From 5efe22ae77a2298a6269dcca717952cfae388cff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CMithali=E2=80=9D?=
<“mithali.parwatkar@finbox.in”>
Date: Fri, 4 Apr 2025 18:37:35 +0530
Subject: [PATCH 5/8] revised content for FCM
---
docs/device-connect/android.md | 22 +++++++++++-----------
1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/docs/device-connect/android.md b/docs/device-connect/android.md
index d12b0de3..96ae080a 100644
--- a/docs/device-connect/android.md
+++ b/docs/device-connect/android.md
@@ -294,7 +294,7 @@ Upon login with a new set of credentials:
Device matching enhances the SDK's ability to associate user identity signals—such as email address, phone number, and name—with behavioral patterns. This improves insight accuracy while maintaining strict privacy boundaries. These values are securely processed on-device and used only for matching purposes.
-:brain: **How It Works**:
+**How It Works**:
- All matching and signal generation are performed locally on the device.
- No personal information (phone number, email, name) is ever transmitted to FinBox servers.
@@ -329,10 +329,6 @@ final DeviceMatch deviceMatch = builder.build();
-::: warning NOTE
-This step is optional but highly recommended for improved insight quality in multi-user or shared-device environments.
-:::
-
Once the in-device values are set, call `setDeviceMatch` before starting the syncs.
@@ -353,17 +349,17 @@ finbox.setDeviceMatch(deviceMatch);
-::: tip 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.
+::: tip
+This step is optional but highly recommended for improved insight quality in multi-user or shared-device environments. Also, for Device Match to work at full potential, the SDK expects `android.permission.READ_SMS` to be accepted by the user.
:::
-## Forward Notifications to SDK (Important)
-Certain phone manufacturers, implement aggressive battery optimization features that kill apps running in the background after a certain period of inactivity. This can prevent the DeviceConnect SDK's continuous syncing from functioning properly, as it relies on background data collection. In such cases, FinBox’s server may need to request data from the SDK when continuous sync has stopped.
+## :iphone: Handling Background Restrictions on Specific Devices
-To enable this functionality, we use Firebase Cloud Messaging (FCM) notifications process. Forwarding these notifications allows the app to "wake up" if it has been killed by the device’s background processes, ensuring continuous data collection. When the app receives an FCM notification, it "wakes up" and continues collecting the necessary data for integration.
+To ensure continuous background syncing—even on devices with aggressive battery optimizations—the SDK supports a silent wake-up mechanism using Firebase Cloud Messaging (FCM). When background sync is disrupted (e.g., due to the app being killed or restricted by the OS), FinBox servers send a silent FCM push to wake up the app. These notifications are invisible to the user and are used solely to reinitialize the SDK’s sync processes in the background.
-Add the following lines inside the overridden `onMessageReceived` method available in the service that extends `FirebaseMessagingService`.
+:wrench: **Implementation**: To enable this functionality, forward relevant FCM messages to the SDK within your `FirebaseMessagingService` class.
+Add the following logic inside your overridden `onMessageReceived()` method
@@ -392,6 +388,10 @@ if(MessagingService.forwardToFinBoxSDK(remoteMessage.getData())) {
+:white_check_mark: **Prerequisites**:
+- Ensure notification permissions are enabled at the OS level.
+- The app must be installed (not uninstalled) for FCM-triggered wake-ups to work
+
## Multi-Process Support (Optional)
DeviceConnect uses a **content provider** to automatically initialize the SDK. However, Android has a limitation: in multi-process applications, **content providers are only initialized in the main process**. This means that any SDK calls from other processes may result in **unstable behavior**
From 27fdce6e5bbc0fdea9482f42004d504d70c059f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CMithali=E2=80=9D?=
<“mithali.parwatkar@finbox.in”>
Date: Fri, 4 Apr 2025 19:09:57 +0530
Subject: [PATCH 6/8] changes to reset, forget , stopperiodicsync
---
docs/device-connect/android.md | 90 +++++++++++++++++++++-------------
1 file changed, 55 insertions(+), 35 deletions(-)
diff --git a/docs/device-connect/android.md b/docs/device-connect/android.md
index 96ae080a..c276e5ff 100644
--- a/docs/device-connect/android.md
+++ b/docs/device-connect/android.md
@@ -266,11 +266,29 @@ finbox.startPeriodicSync();
:repeat: **Functionality Overview**:
- Initiates periodic background syncing of user data from all enabled sources (e.g., SMS, installed apps etc).
- Sync intervals are controlled using the `setSyncFrequency` method.
-- Default collection frequency is 8 hrs and this is configurable.
- Sync operations are optimized for battery and network conditions.
- Automatically pauses syncing when the battery is low.
- Resumes syncing when the device is charging or reconnected to a network
+By default, the sync frequency is set to **8 hours**. You can customize this frequency by calling the `setSyncFrequency` method and passing your preferred interval **in seconds** as an argument. Ensure this method is invoked after the user is created.
+
+
+
+
+```kotlin
+finbox.setSyncFrequency(12 * 60 * 60)
+```
+
+
+
+
+```java
+finbox.setSyncFrequency();
+```
+
+
+
+
:lock: **Permissions-Driven Behavior**:
- Data syncing respects all runtime permissions granted by the user. If any required permission (e.g., SMS, Installed etc) is not granted or is later revoked:
- The SDK will skip syncing from that data source.
@@ -290,7 +308,7 @@ Upon login with a new set of credentials:
- This resumes background syncing immediately, ensuring minimal delay in starting data collection for the new session.
:::
-## :lock: Match Details on Device (Important)
+## Match Details on Device (Important)
Device matching enhances the SDK's ability to associate user identity signals—such as email address, phone number, and name—with behavioral patterns. This improves insight accuracy while maintaining strict privacy boundaries. These values are securely processed on-device and used only for matching purposes.
@@ -354,7 +372,7 @@ This step is optional but highly recommended for improved insight quality in mul
:::
-## :iphone: Handling Background Restrictions on Specific Devices
+## Handling Background Restrictions on Specific Devices
To ensure continuous background syncing—even on devices with aggressive battery optimizations—the SDK supports a silent wake-up mechanism using Firebase Cloud Messaging (FCM). When background sync is disrupted (e.g., due to the app being killed or restricted by the OS), FinBox servers send a silent FCM push to wake up the app. These notifications are invisible to the user and are used solely to reinitialize the SDK’s sync processes in the background.
@@ -439,30 +457,12 @@ FinBox.initLibrary(this);
-## Handle Sync Frequency (Optional)
-
-By default, the sync frequency is set to **8 hours**. You can customize this frequency by calling the `setSyncFrequency` method and passing your preferred interval **in seconds** as an argument. Ensure this method is invoked after the user is created
-
-
-
-
-```kotlin
-finbox.setSyncFrequency(12 * 60 * 60)
-```
-
-
-
-
-```java
-finbox.setSyncFrequency();
-```
-
-
-
-
-## Cancel Periodic Sync
+## Handling User Logout: Stopping Background Sync
-Make sure to cancel data synchronization tasks when the user logs out of the app by using the `stopPeriodicSync` method. This ensures that no background sync operations continue unnecessarily, maintaining data security.
+When a user logs out of the app, it is important to explicitly stop ongoing background data synchronization to prevent unnecessary activity and ensure compliance with data handling standards.
+Call the `stopPeriodicSync` method during logout to:
+- Halt all future data sync operations
+- Maintain data privacy and session isolation
@@ -481,9 +481,9 @@ finbox.stopPeriodicSync();
-## Reset User Data
+## Resetting Local User Data
-If you need to clear a user's data stored on the device and initiate a fresh data sync, use the `resetData` method. This ensures that all previous data is removed, and syncing starts from scratch.
+Use the `resetData` method to clear all locally cached data associated with the current user. This is typically used during logout flows or re-authentication scenarios where a clean local state is required.
@@ -502,9 +502,15 @@ FinBox.resetData();
+**Behavior**:
+- Deletes all locally stored data associated with the active customerId.
+- Does not affect server-side data.
+- Can be safely called while offline; the reset is performed on-device.
+- Syncing can be restarted by simply calling startPeriodicSync() again.
+
## Forget User
-If a user requests to be forgotten, use the `forgetUser` method. This will delete all user details from our system, ensuring this meets digital guidelines for right to be forgotten.
+Use the `forgetUser` method to permanently delete all user data from FinBox systems. This should be used to comply with requests under data privacy laws (e.g., GDPR) or full account deletion flows.
@@ -523,10 +529,24 @@ FinBox.forgetUser();
-::: tip RECOMMENDATION
+**Behavior**:
+- Deletes all server-side data associated with the user.
+- Removes the linked customerId and any stored insights.
+- Ensures full compliance with the "Right to be Forgotten."
-- When a user logs out, call both `stopPeriodicSync` and `resetData` to:
- - Stop any ongoing periodic sync processes.
- - Clear existing user data.
- This approach ensures a clean state before the next user session.
-:::
+:warning: Important: After this call, the user cannot be re-associated without a new createUser() invocation
+
+::: tip
+:ballot_box_with_check: Recommended Logout Flow:
+When a user logs out of the app, follow this flow to ensure clean separation of sessions:
+`stopPeriodicSync` > `resetData`
+
+**Why this matters** :
+- stopPeriodicSync() halts background sync tasks.
+- resetData() ensures no residual information remains on the device.
+
+For full account deletion, combine:
+`stopPeriodicSync` > `resetData` > `forgetUser`
+
+- This will remove local, server-side, and identity-level data completely.
+:::
\ No newline at end of file
From 026aac9ba4b38c27bae2c809d46701168bbd85ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CMithali=E2=80=9D?=
<“mithali.parwatkar@finbox.in”>
Date: Fri, 4 Apr 2025 19:11:24 +0530
Subject: [PATCH 7/8] fine tuning
---
docs/device-connect/android.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/device-connect/android.md b/docs/device-connect/android.md
index c276e5ff..2fa91f08 100644
--- a/docs/device-connect/android.md
+++ b/docs/device-connect/android.md
@@ -226,7 +226,7 @@ FinBox.createUser("CLIENT_API_KEY", "CUSTOMER_ID",
The response (success or failure) is handled using the `FinBoxAuthCallback` callback.
-:repeat: **Behavior Notes**:
+:repeat: **Behavior**:
- The method is idempotent: calling it repeatedly with the same customerId will not cause an error.
- If the customer is already registered, the SDK will return a success response and continue as expected.
- If invalid credentials or customer ID are provided, onError() is triggered with a specific error code
@@ -502,7 +502,7 @@ FinBox.resetData();
-**Behavior**:
+:repeat: **Behavior Notes**:
- Deletes all locally stored data associated with the active customerId.
- Does not affect server-side data.
- Can be safely called while offline; the reset is performed on-device.
@@ -529,7 +529,7 @@ FinBox.forgetUser();
-**Behavior**:
+:repeat: **Behavior Notes**:
- Deletes all server-side data associated with the user.
- Removes the linked customerId and any stored insights.
- Ensures full compliance with the "Right to be Forgotten."
From 9413d8115115ef07532c22e877cb14b1135f59ad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CMithali=E2=80=9D?=
<“mithali.parwatkar@finbox.in”>
Date: Wed, 21 May 2025 16:50:47 +0530
Subject: [PATCH 8/8] removed redundancy in intro of compatible version
---
docs/device-connect/android.md | 15 ++++++++-------
1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/docs/device-connect/android.md b/docs/device-connect/android.md
index 2fa91f08..571dca5a 100644
--- a/docs/device-connect/android.md
+++ b/docs/device-connect/android.md
@@ -7,16 +7,17 @@ The DeviceConnect Android SDK enables the collection of anonymized, non-PII data
## Requirements
+To use the DeviceConnect Android SDK, your project must meet the following minimum setup:
-To ensure compatibility and optimal performance of the SDK, the following minimum requirements must be met:
-- **Android OS Version**: Android 5.0 (Lollipop) or higher (API Level 21+)
-- **Java Version**: Java 8 or higher
-- **Support Libraries**: AndroidX libraries are mandatory
+- Android OS: API Level 21 (Android 5.0 Lollipop) or higher
+- Java Compatibility: Java 8 (language features)
+- Libraries: AndroidX support libraries are required
::: warning NOTE
-The SDK is built using **Java 8** language features, which are not fully supported on **Android 7.0** and below.
-To maintain compatibility with older devices, it is essential to **enable Java 8 desugaring** in your project.
-Devices running **Android 8.0** and above **do not require desugaring**, as Java 8 support is natively available.
+The SDK uses Java 8 language features.
+For devices running Android 7.0 (API level < 26) and below, you must enable Java 8 desugaring in your project setup.
+This ensures compatibility, as these devices do not natively support Java 8 features.
+Desugaring is not required for devices running Android 8.0 (API level 26) and above.
:::