Usage: Availability and permissions

Check permissions and Samsung Health app availability.

Check availability

Before proceeding further, ensure that the Samsung Health app is installed and ready to be used, call checkSamsungHealthAvailability:

Status	Description	What to do
INSTALLED	Samsung Health is installed and ready to be used.	Proceed to check permissions
NOT_INSTALLED	Samsung Health is not installed.	Prompt the user to install Samsung Health.
OUTDATED	The version of Samsung Health is too old.	Prompt the user to update Samsung Health.
DISABLED	Samsung Health is disabled.	Prompt the user to enable Samsung Health.
NOT_READY	The user didn't perform an initial process, such as agreeing to the Terms and Conditions.	Prompt the user to open and complete the onboarding process of Samsung Health.

rookSamsung.checkSamsungHealthAvailability().fold(
    { availability ->
        // Success
    },
    {
        // Hanlde errors
    },
)

Samsung Health permissions

These are permissions used to extract data, each Samsung Health data type is subject to a different permission, below you can see the list of permissions ROOK needs:

• ACTIVITY_SUMMARY
• BLOOD_GLUCOSE
• BLOOD_OXYGEN
• BLOOD_PRESSURE
• BODY_COMPOSITION
• EXERCISE
• EXERCISE_LOCATION
• FLOORS_CLIMBED
• HEART_RATE
• NUTRITION
• SLEEP
• STEPS
• WATER_INTAKE

Check permissions

To check permissions call checkSamsungHealthPermissions:

val hasAllSamsungHealthPermissions = rookSamsung.checkSamsungHealthPermissions(samsungPermissions).fold(
    { hasAllPermissions ->
        hasAllPermissions
    },
    { throwable ->
        false
    }
)

The previous function will check for all permissions, to check if at least one permission is granted, call checkSamsungHealthPermissionsPartially:

val hasSomeSamsungHealthPermissions = rookSamsung.checkSamsungHealthPermissionsPartially(samsungPermissions).fold(
    { hasSomePermissions ->
        hasSomePermissions
    },
    { throwable ->
        false
    }
)

Request permissions

To request permissions call requestSamsungHealthPermissions:

rookSamsung.requestSamsungHealthPermissions(samsungPermissions).fold(
    {
        when (it) {
            SHRequestPermissionsStatus.ALREADY_GRANTED -> {
                // Permissions already granted, update your UI
            }

            SHRequestPermissionsStatus.REQUEST_SENT -> {
                // Wait for broadcast result
            }
        }
    },
    {
        // Handle error
    }
)

This function will return a SHRequestPermissionsStatus with 2 possible values:

• ALREADY_GRANTED: The permissions are already granted thus no request was sent.
• REQUEST_SENT: The permissions request was sent, and you can get notified if the permissions were granted or denied using a BroadcastReceiver.

The BroadcastReceiver can be registered using the SamsungHealthPermission.ACTION_SAMSUNG_HEALTH_PERMISSIONS action and will contain the following extras:

• SamsungHealthPermission.EXTRA_SAMSUNG_HEALTH_PERMISSIONS_GRANTED: Boolean describing if all Samsung Health permissions were granted.
• SamsungHealthPermission.EXTRA_SAMSUNG_HEALTH_PERMISSIONS_PARTIALLY_GRANTED: Boolean describing if some (at least one)Samsung Health permissions were granted. Note that if EXTRA_SAMSUNG_HEALTH_PERMISSIONS_GRANTED is true, this will also be true.

// 1.- Create broadcast receiver
private val samsungHealthBroadcastReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        val allPermissionsGranted = intent?.getBooleanExtra(
            /* name = */ SamsungHealthPermission.EXTRA_SAMSUNG_HEALTH_PERMISSIONS_GRANTED,
            /* defaultValue = */ false
        ) ?: false

        val permissionsPartiallyGranted = intent?.getBooleanExtra(
            /* name = */ SamsungHealthPermission.EXTRA_SAMSUNG_HEALTH_PERMISSIONS_PARTIALLY_GRANTED,
            /* defaultValue = */ false
        ) ?: false

        // This will make your app more flexible by allowing it to work even if some permissions are not granted:
        val permissionsGranted = allPermissionsGranted || permissionsPartiallyGranted

        // Updated your UI
    }
}

// 2.- Register broadcast receiver (onCreate)
ContextCompat.registerReceiver(
    context,
    samsungHealthBroadcastReceiver,
    IntentFilter(SamsungHealthPermission.ACTION_SAMSUNG_HEALTH_PERMISSIONS),
    ContextCompat.RECEIVER_EXPORTED,
)

// 3.- Request permissions
rookSamsung.requestSamsungHealthPermissions(samsungPermissions).fold(
    {
        when (it) {
            SHRequestPermissionsStatus.ALREADY_GRANTED -> {
                // Permissions already granted, update your UI
            }

            SHRequestPermissionsStatus.REQUEST_SENT -> {
                // Wait for broadcast result
            }
        }
    },
    {
        // Handle error
    }
)

// 4.- Unregister broadcast receiver (onDestroy)
context.unregisterReceiver(samsungHealthBroadcastReceiver)

Customizing permissions

The requestSamsungHealthPermissions, checkSamsungHealthPermissions and checkSamsungHealthPermissionsPartially functions accept a set of SamsungHealthPermission so you can only request/check the permissions your app truly needs:

val samsungPermissions: Set<SamsungHealthPermission> = setOf(
    SamsungHealthPermission.ACTIVITY_SUMMARY,
    SamsungHealthPermission.BODY_COMPOSITION,
    SamsungHealthPermission.EXERCISE,
    SamsungHealthPermission.EXERCISE_LOCATION,
    SamsungHealthPermission.HEART_RATE,
    SamsungHealthPermission.SLEEP,
    SamsungHealthPermission.STEPS,
)

rookSamsung.requestSamsungHealthPermissions(samsungPermissions).fold(
    { requestPermissionsStatus ->
        // Success
    },
    {
        // Handle error
    },
)

Optimization permissions

Some users want to have as much battery life as possible, so they have power saving mode always active, also some phone manufactures add their own energy restriction on top of Android's, these restrictions are mostly enabled by default and depending on the device will add a delay to our background services; Background Sync or even stop them completely.

We have added mutiple optimization paths you can follow:

info

The following are optional permissions, you can use the Background Sync component without these permission, however we recommend to add a button to ask this permission in a support page of your application so users can grant it if they are experiencing interruptions with the service.

Alarm permissions

The SDK uses the android.permission.SCHEDULE_EXACT_ALARM (pre-included in SDK's manifest) to improve the lifetime of Background Services in battery constrained scenarios.

To check permissions call checkExactAlarmPermissions:

val hasAlarmPermissions = rookSamsung.checkExactAlarmPermissions()

To request permissions call requestExactAlarmPermissions:

val requestPermissionsStatus = rookSamsung.requestExactAlarmPermissions()

when (requestPermissionsStatus) {
    SHRequestPermissionsStatus.ALREADY_GRANTED -> {
        // Permissions already granted.                                 
    }

    SHRequestPermissionsStatus.REQUEST_SENT -> {
        // Because this is a special app access permission, 
        // there is no callback the recommended pattern is to call checkExactAlarmPermissions again.                                                    
    }
}

info

On API 26–30 exact alarms are unrestricted so checkExactAlarmPermissions/requestExactAlarmPermissions will always return true/SHRequestPermissionsStatus.REQUEST_SENT.

Battery optimizations

To check if battery optimizations are disabled call checkBatteryOptimizationsDisabled:

val batteryOptimizationsDisabled = rookSamsung.checkBatteryOptimizationsDisabled()

To request disabling battery optimizations call requestDisableBatteryOptimizations:

val requestPermissionsStatus = rookSamsung.requestDisableBatteryOptimizations()

when (requestPermissionsStatus) {
    SHRequestPermissionsStatus.ALREADY_GRANTED -> {
        // Battery optimizations are already disabled                                 
    }

    SHRequestPermissionsStatus.REQUEST_SENT -> {
        // Because this is a special app access permission, 
        // there is no callback the recommended pattern is to call checkBatteryOptimizationsDisabled again.                                                    
    }
}

Auto start

Brands like OPPO, One Plus and Xiaomi implement a custom Auto Start restriction that limits app's background execution. You can check if the current device belongs to an OEM that enforces this restriction with requiresOemAutoStartSetup:

val hasAutoStartRestriction = rookSamsung.requiresOemAutoStartSetup()

info

Detection works by probing whether any known OEM settings screen resolves on the device. A true result means the OEM management system exists it does not mean auto start is currently blocked for this specific app. Use this to decide whether to prompt the user to open the OEM setup screen.

To open the brand-specific settings screen call openOemAutoStartSetup:

rookSamsung.openOemAutoStartSetup().fold(
    { requestPermissionsStatus ->
        when (requestPermissionsStatus) {
            SHRequestPermissionsStatus.ALREADY_GRANTED -> {
                // The device has no OEM screen                                 
            }

            SHRequestPermissionsStatus.REQUEST_SENT -> {
                // Because this is a brand specific there is no way to know the user's choice.                                                    
            }
        }
    },
    {
        // Manage error
    },
)