Skip to main content

Extra: Background steps

Track and upload steps from Android System in background.

Introduction​

This feature included in rook-sdk 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.

RookStepsCounter​

You can call RookStepsCounter functions by creating an instance with a context:

// It's recommended to use this instance as a singleton with a ServiceLocator or Dependency Injection.
val rookStepsCounter = RookStepsCounter(context)

rookStepsCounter.doSomething()

Or using the Companion object and providing a context with each call:

RookStepsCounter.doSomething(context)

Check availability​

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

val isAvailable = rookStepsCounter.isStepsCounterAvailable()

Permissions​

To use RookStepsCounter 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

RookStepsCounter 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 RookStepsCounter normally. RookStepsCounter 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.

The notification has the next default values:

  • Icon
  • Title: Steps service
  • Content: Tracking your steps…

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:

rookStepsCounter.enableStepsCounter().fold(
    {
        // RookStepsCounter start request send successfully.
        // Use RookStepsCounter.isStepsCounterActive() to ensure proper activation.
    },
    {
        // Handle error 
    }
)

To stop tracking steps call disableStepsCounter:

rookStepsCounter.disableStepsCounter().fold(
    {
        // RookStepsCounter stop request send successfully. 
        // Use RookStepsCounter.isStepsCounterActive() to ensure proper deactivation.
    },
    {
        // 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:

rookStepsCounter.getTodayStepsCount().fold(
    { todaySteps ->
        // Steps obtained successfully.
    },
    {
        // 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.