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. +::: -::: 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 +: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. + + + + + + :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 - - - - - - -## 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 -## 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. +**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. -::: 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. :::