Skip to main content

Extra: Background steps

Track and upload steps from Android System in background.

Introduction​

This feature included in rook_sdk_health_connect enables automatic extraction and upload of steps without needing to install Health Connect.

Android Studio​

Go to the main Android Studio section to see the IDE configuration.

Getting started​

Android configuration​

Go to the main Android configuration section to see the basic configuration.

Logging​

Go to the main Logging section to configure logs.

Usage​

Initialize​

Go to the main Initialize and Update userID sections to initialize.

Check availability​

Before proceeding further, you need to ensure the user's device has the required sensors. Call isAvailable:

void isAvailable() async {
  final isAvailable = await AndroidStepsManager.isAvailable();
}

Permissions​

To use AndroidStepsManager you will need:

Customizing the foreground service notification​

The steps manager uses a foreground Service which requires a notification to be permanently displayed.

To use your own resources you need to reference them in the AndroidManifest.xml file:


<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <meta-data
            android:name="io.tryrook.service.notification.STEPS_ICON"
            android:resource="@drawable/my_custom_icon"/>

        <meta-data
            android:name="io.tryrook.service.notification.STEPS_TITLE"
            android:resource="@string/my_custom_title"/>

        <meta-data
            android:name="io.tryrook.service.notification.STEPS_CONTENT"
            android:resource="@string/my_custom_content"/>
    </application>
</manifest>
info

Starting on Android 13 (SDK 33) this notification can be dismissed without finishing the service associated with it, then the service will be displayed in the active apps section (This may vary depending on device brand).

Enabling/Disabling​

To start tracking steps call enableBackgroundAndroidSteps:

void startStepsTracker() async {
  try {
    await AndroidStepsManager.enableBackgroundAndroidSteps();

    // Success
  } catch (exception) {
    // Handle error
  }
}

To stop tracking steps call disableBackgroundAndroidSteps:

void stopStepsTracker() async {
  try {
    await AndroidStepsManager.disableBackgroundAndroidSteps();

    // Success
  } catch (exception) {
    // Handle error
  }
}
info

Calling enableBackgroundAndroidSteps/ disableBackgroundAndroidSteps when the service is active/inactive will do nothing, however you can check if the service is active with isBackgroundAndroidStepsActive:

Sync today step count​

Call syncTodayAndroidStepsCount to retrieve and upload current day steps count:

void getTodaySteps() {
  AndroidStepsManager.syncTodayAndroidStepsCount().then((todaySteps) {
    // Success
  }).catchError((exception) {
    // Handle error
  });
}
danger

This function is resource intensive, don't call it too frequently, as it could have a negative impact in your users experience.

Additional information​

Auto start​

After a call to enableBackgroundAndroidSteps if the device is restarted the Foreground service will start after the user unlocks their device for the first time (This may vary depending on device brand). This behaviour will be stopped when calling disableBackgroundAndroidSteps.

Considerations​

The steps service is designed to always be active but there are certain scenarios where the service could not behave as intended:

  • If the user force closes the application from settings, and then restarts their device the service may not be able to restart.
  • The steps are scheduled to be uploaded every hour from the time enableBackgroundAndroidSteps was called, however it's not possible to guarantee the exact execution time as this depends on how the Android System manages the device resources.