Skip to main content

Usage: Sync health data automatically

Schedule automatic syncs in background.

Background sync​

Background Sync allows to schedule an automatic syncs every hour in the background.

Each time background sync is triggered the following operations will happen:

  1. Sync today events:
    1. Activity
    2. Steps
    3. Calories
    4. Body Metrics
    5. Heart Rate
    6. Oxygenation
    7. Hydration
    8. Nutrition
    9. Blood Pressure
    10. Blood Glucose
  2. Sync today summaries
    1. Sleep
      • If at least 4 hours have passed since the last successful sync
      • If the "new" data is equal to the previous sync it won't be synced again.
  3. Sync yesterday summaries
    1. Sleep
      • If at least 4 hours have passed since the last successful sync
      • If the "new" data is equal to the previous sync it won't be synced again.
    2. Physical
      • If at least 4 hours have passed since the last successful sync
      • If the "new" data is equal to the previous sync it won't be synced again.
    3. Body
      • If at least 4 hours have passed since the last successful sync
      • If the "new" data is equal to the previous sync it won't be synced again.
  4. Sync historic data
    1. Activity events
      • If not synced yet 29 days, starting from yesterday
    2. Sleep summary
      • If not synced yet 29 days, starting from yesterday
    3. Physical summary
      • If not synced yet 29 days, starting from yesterday
    4. Body summary
      • If not synced yet 29 days, starting from yesterday

Permissions​

To use Background Sync you will need:

info

Background Sync also requires a user id, so it's possible that the first time nothing will happen, only after a user id is configured and all necessary permissions are granted the automatic sync will happen within the next hour.

Usage​

To schedule a background sync for every hour call schedule:

rookSamsung.schedule(enableLogs = isDebug)

We recommend adding an extra call to schedule in the onCreate callback of your Application class:

class MyAplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // It's a good practice to ask your users if they want to enable this behaviour
        // and wrap this line inside an if which checks a preferences-stored flag
        if (userAllowedBackgroundSync) {
            RookSamsungObject.schedule(this, enableLogs = isDebug)
        }
    }
}
tip

It's a good practice to ask your users if they want to enable this behaviour, then save their preference in local storage and call schedule conditionally.

To cancel any scheduled background sync call cancel:

rookSamsung.cancel()

If you want to check the current state of Background Sync call isScheduled or isScheduledFlow (Experimental):

fun howToCheckBackgroundSyncState() {
    // Get latest state
    coroutineScope.launch {
        val isScheduled: Boolean = rookSamsung.isScheduled().getOrDefault(defaultValue = false)

        // Update UI
    }

    // Receive real-time updates
    @OptIn(ExperimentalRookSamsungApi::class)
    viewModelScope.launch {
        rookSamsung.isScheduledFlow().collectLatest { isScheduled: Boolean ->
            // Update UI  
        }
    }
}
warning

Don't use isScheduled or isScheduledFlow to decide if you should call schedule, if you do this future improvements to the Background Sync behavior may not be applied, the "isScheduled" functions are only meant for UI related purposes.

Execution/Skip conditions​

Each periodic execution of Background Sync will check for some requirements, and will skip the execution if one the following conditions is true:

  • The device battery is low.
  • The device storage is low.
  • The device is not connected to the internet.
  • The userID hasn't been configured.
  • The user hasn't granted Samsung Health Permissions.
  • There is an error initializing the SDK.