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 AndroidStepsCounter.isStepsCounterAvailable();
}

Permissions​

To use AndroidStepsCounter you will need:

  • Android permissions: Go to the main Android Permissions section to see the implementation.
  • Alarms permissions (Optional): Go to the main Alarm permissions section to see the implementation.
Alarm permissions

AndroidStepsCounter uses the SCHEDULE_EXACT_ALARM permission to improve its lifetime in battery constrained scenarios, however this is optional, you can skip requesting this permission to your users and still use AndroidStepsCounternormally. AndroidStepsCounter will only schedule an alarm if the permission is granted.

IMPORTANT: You need to call enableStepsCounter again after requesting the alarms' permission.

Customizing the foreground service notification​

The steps counter 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 enableStepsCounter:

void startStepsTracker() async {
  try {
    await AndroidStepsCounter.enableStepsCounter();

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

To stop tracking steps call disableStepsCounter:

void stopStepsTracker() async {
  try {
    await AndroidStepsCounter.disableStepsCounter();

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

Calling enableStepsCounter/ disableStepsCounter when the service is active/inactive will do nothing, however you can check if the service is active with isStepsCounterActive:

Sync today step count​

Call getTodayStepsCount to retrieve and upload current day steps count:

void getTodaySteps() {
  AndroidStepsCounter.getTodayStepsCount().then((todaySteps) {
    // Success
  }).catchError((exception) {
    // Handle error
  });
}
warning

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 enableStepsCounter 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 behavior will be stopped when calling disableStepsCounter.

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 enableStepsCounter 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.