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.

RookStepsManager​

You can call RookStepsManager 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 rookStepsManager = RookStepsManager(context)

rookStepsManager.doSomething()

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

RookStepsManager.doSomething(context)

Check availability​

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

val isAvailable = rookStepsManager.isAvailable()

Permissions​

To use RookStepsManager you will need:

Customizing the foreground service notification​

The steps manager 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 enableBackgroundAndroidSteps:

rookStepsManager.enableBackgroundAndroidSteps().fold(
    {
        // RookStepsManager start request send successfully. 
        // Every 12 hours a physical summary with the current steps of the day will be uploaded to ROOK servers
        // Use RookStepsManager.isActive() to ensure proper activation.
    },
    { throwable ->
        val error = when (throwable) {
            is SDKNotInitializedException -> "SDKNotInitializedException: ${throwable.message}"
            is MissingAndroidPermissionsException -> "MissingAndroidPermissionsException: ${throwable.message}"
            else -> throwable.message
        }

        // Error sending RookStepsManager start request. 
    }
)

To stop tracking steps call disableBackgroundAndroidSteps:

rookStepsManager.disableBackgroundAndroidSteps().fold(
    {
        // RookStepsManager stop request send successfully. 
        // Use RookStepsManager.isActive() to ensure proper deactivation.
    },
    { throwable ->
        val error = when (throwable) {
            is SDKNotInitializedException -> "SDKNotInitializedException: ${throwable.message}"
            else -> throwable.message
        }

        // Error sending RookStepsManager stop request. 
    }
)
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:

rookStepsManager.syncTodayAndroidStepsCount().fold(
    { todaySteps ->
        // Steps obtained successfully.
    },
    { throwable ->
        val error = when (throwable) {
            is SDKNotInitializedException -> "SDKNotInitializedException: ${throwable.message}"
            is SDKNotAuthorizedException -> "SDKNotAuthorizedException: ${throwable.message}"
            else -> throwable.message
        }

        // Error obtaining steps.
    }
)
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.