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 enableBackground:

void enableBackgroundSync() async {
  try {
    await RookSamsung.enableBackground(enableNativeLogs: isDebug);

    // Background sync enabled
  } catch (error) {
    // Handle error
  }
}

We recommend adding an extra call to enableBackground in the main method:

void main() {
  // Ensure that the plugin is ready
  WidgetsFlutterBinding.ensureInitialized();

  if (Platform.isAndroid) {
    enableAndroidBackgroundSync();
  } else {
    enableIOSBackgroundSync();
  }

  runApp(App());
}

void enableAndroidBackgroundSync() async {
  try {
    final userAllowedBackgroundSync = await AppPreferences().getUserAllowedBackgroundSync();

    if (userAllowedBackgroundSync) {
      await RookSamsung.enableBackground(enableNativeLogs: isDebug);
    }
  } catch (error) {
    // Log
  }
}

void enableIOSBackgroundSync() async {
  // Go to IOS documentation to learn how to enable background sync
}
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 enableBackground conditionally.

To cancel any scheduled background sync call disableBackground:

void disableBackgroundSync() async {
  try {
    await RookSamsung.disableBackground();

    // Background sync disabled
  } catch (error) {
    // Handle error
  }
}

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

void checkBackgroundSyncState() async {
  try {
    final isScheduled = await RookSamsung.isScheduled();

    // Update your UI
  } catch (error) {
    // Handle error
  }
}
// 1.- Create a stream subscription
StreamSubscription<bool>? streamSubscription;

// 2.- Listen to stream
streamSubscription = RookSamsung.isScheduledUpdates.listen((isScheduled) {
// Update UI
});

// 3.- Stop listening to the stream
streamSubscription?.cancel();
warning

Don't use isScheduled or isScheduledUpdates to decide if you should call enableBackground, 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.