Guides

Sensors

Since Sahha requires device data (such as steps, sleep and other data) in order to analyse health, we need to access the devices sensors. This guide will show you how to configure, and manage device sensors and the data they collect.

The Sahha SDK handles device sensors for your app and acts as a bridge between your app and the device sensors. This simplifies the process of collecting and analyzing device data.

Sensor Settings

You can specify which sensors for the Sahha SDK to use. We suggest asking the user for permission for access to only the sensors that your app needs. This will lower the chance that the user will reject your permission request.

Choose if you want to request permission for all, some, or no sensors.

If you leave the Sensor Settings value to the default value of null, ALL AVAILABLE SENSORS will be requested.

If you set the Sensor Settings value to an array of some specific sensors, ONLY THOSE SENSORS will be requested.

If you set the Sensor Settings value to an empty array [], you will receive an ERROR.

Some sensors are not available on all platforms.

SahhaSensor Android Sensor iOS Sensor
gender Sensor Not Available biologicalSex
date_of_birth Sensor Not Available dateOfBirth
sleep SleepSessionRecord sleepAnalysis
step_count StepsRecord stepCount
floor_count FloorsClimbedRecord flightsClimbed
heart_rate HeartRateRecord heartRate
resting_heart_rate RestingHeartRateRecord restingHeartRate
walking_heart_rate_average Sensor Not Available walkingHeartRateAverage
heart_rate_variability_rmssd HeartRateVariabilityRmssdRecord Sensor Not Available
heart_rate_variability_sdnn Sensor Not Available heartRateVariabilitySDNN
blood_pressure_systolic BloodPressureRecord bloodPressureSystolic
blood_pressure_diastolic BloodPressureRecord bloodPressureDiastolic
blood_glucose BloodGlucoseRecord bloodGlucose
vo2_max Vo2MaxRecord vo2Max
oxygen_saturation OxygenSaturationRecord oxygenSaturation
respiratory_rate RespiratoryRateRecord respiratoryRate
active_energy_burned ActiveCaloriesBurnedRecord activeEnergyBurned
basal_energy_burned Sensor Not Available basalEnergyBurned
total_energy_burned TotalCaloriesBurnedRecord Sensor Not Available
basal_metabolic_rate BasalMetabolicRateRecord Sensor Not Available
time_in_daylight Sensor Not Available timeInDaylight
body_temperature BodyTemperatureRecord bodyTemperature
basal_body_temperature BasalBodyTemperatureRecord basalBodyTemperature
sleeping_wrist_temperature Sensor Not Available appleSleepingWristTemperature
height HeightRecord height
weight WeightRecord bodyMass
lean_body_mass LeanBodyMassRecord leanBodyMass
body_mass_index Sensor Not Available bodyMassIndex
body_fat BodyFatRecord bodyFatPercentage
body_water_mass BodyWaterMassRecord Sensor Not Available
bone_mass BoneMassRecord Sensor Not Available
waist_circumference Sensor Not Available waistCircumference
stand_time Sensor Not Available appleStandTime
move_time Sensor Not Available appleMoveTime
exercise_time Sensor Not Available appleExerciseTime
activity_summary Sensor Not Available activitySummary
device_lock devicelock Sensor Not Available
exercise ExerciseSessionRecord workout 
enum class SahhaSensor {
    gender,
    date_of_birth,
    sleep,
    step_count,
    floor_count,
    heart_rate,
    resting_heart_rate,


    @Deprecated(
        message = IOS_ONLY,
        level = DeprecationLevel.WARNING
    )
    walking_heart_rate_average,


    @Deprecated(
        message = "$IOS_ONLY. Please use heart_rate_variability_rmssd for Android instead",
        replaceWith = ReplaceWith("heart_rate_variability_rmssd"),
        level = DeprecationLevel.WARNING
    )
    heart_rate_variability_sdnn,
    heart_rate_variability_rmssd,
    blood_pressure_systolic,
    blood_pressure_diastolic,
    blood_glucose,
    vo2_max,
    oxygen_saturation,
    respiratory_rate,
    active_energy_burned,


    @Deprecated(
        message = IOS_ONLY,
        level = DeprecationLevel.WARNING
    )
    basal_energy_burned,
    total_energy_burned,
    basal_metabolic_rate,


    @Deprecated(
        message = IOS_ONLY,
        level = DeprecationLevel.WARNING
    )
    time_in_daylight,
    body_temperature,
    basal_body_temperature,


    @Deprecated(
        message = IOS_ONLY,
        level = DeprecationLevel.WARNING
    )
    sleeping_wrist_temperature,
    height,
    weight,
    lean_body_mass,


    @Deprecated(
        message = IOS_ONLY,
        level = DeprecationLevel.WARNING
    )
    body_mass_index,
    body_fat,
    body_water_mass,
    bone_mass,


    @Deprecated(
        message = IOS_ONLY,
        level = DeprecationLevel.WARNING
    )
    waist_circumference,


    @Deprecated(
        message = IOS_ONLY,
        level = DeprecationLevel.WARNING
    )
    stand_time,


    @Deprecated(
        message = IOS_ONLY,
        level = DeprecationLevel.WARNING
    )
    move_time,


    @Deprecated(
        message = IOS_ONLY,
        level = DeprecationLevel.WARNING
    )
    exercise_time,
    activity_summary,
    device_lock,
    exercise,
}

(Android) Uses Permission - IMPORTANT INFO

Specifying Sensors for Android

For every sensor you specify in getSensorStatus or enableSensors, you will need to include matching uses-permission values in your AndroidManifest.xml.

View the SDK Integration guide for Android .

If the values do not match, you are likely to receive build errors and risk your app being rejected on the Google Play Store!

About the device sensor status

The sensors have multiple possible statuses which indicate whether they are enabled or disabled or anywhere in between. 

enum class SahhaSensorStatus {
    pending, // Sensors pending User permission
    unavailable, // Sensors not supported by the User's device
    disabled, // Sensors disabled by the User
    enabled // Sensors enabled by the User
}

(iOS) Permission Privacy - IMPORTANT INFO

Apple limits the ability to detect the true sensor status to protect user privacy.

Apple documentation:

To help protect the user’s privacy, your app doesn’t know whether the user granted or denied permission to read data from HealthKit. If the user denied permission, attempts to query data from HealthKit return only samples that your app successfully saved to the HealthKit store.

This means that if a Sensor is available, the only possible SensorStatus is:

  • pending if you have not already prompted the user for permission yet
  • enabled if you have already prompted the user for permission

The disabled SensorStatus is not triggered even if the user declines permission.

The disabled SensorStatus is only included in the iOS SDK to keep parity with the Android SDK.

Please read the official Apple documentation to better understand authorizing access to health data for iOS.

Authorizing access to health data for iOS

Getting the device sensor status

You can check the current status of the sensors by calling getSensorStatus. This method is asynchronous and will return the updated SahhaSensorStatus in its callback.

Configure the SDK before you Get Sensor Status

On app launch, SensorStatus will always be pending. You must configure the SDK before you can get the correct SensorStatus.

We suggest calling getSensorStatus in the callback of configure. 

// Get status of `step_count` and `sleep` sensors
Sahha.getSensorStatus(this@MainActivity,
    setOf<SahhaSensor>(SahhaSensor.step_count, SahhaSensor.sleep))
{ error, status ->
    if (error != null) {
        println(error)
    } else if (status == SahhaSensorStatus.pending) {
        // Sensors are NOT enabled and ready - Show your custom UI before asking for user permission
    } else if (status == SahhaSensorStatus.enabled) {
        // Sensors are enabled and ready
    } else {
        // Sensors are disabled or unavailable
    }
}

Enabling device sensors

Before the SDK can start collecting data, you will need to enable sensors by calling enableSensors. This method is asynchronous and will return the updated SahhaSensorStatus in its callback. 

// Enable `step_count` and `sleep` sensors
Sahha.enableSensors(this@MainActivity,
    setOf<SahhaSensor>(SahhaSensor.step_count, SahhaSensor.sleep))
{ error, status ->
    if (error != null) {
        println(error)
    } else if (status == SahhaSensorStatus.enabled) {
        // Sensors are enabled and ready
    } else {
        // Sensors are disabled or unavailable
    }
}

(iOS) Sleep Sensor - IMPORTANT INFO

Setup Sleep Before Using the SDK

In order for the Sahha SDK to collect data from the sleep sensor, Sleep functionality must be enabled by your mobile user BEFORE calling enableSensors.

We suggest checking if your user has seen the HealthKit permission screen before enabling the sleep sensor. If the status is pending, this is the perfect time to show your custom UI asking your user to setup Sleep in the Health App.

Please read the official Apple documentation to help your users setup Sleep for iOS.

Sleep for iOS

Open App Settings

It's possible for your app user to disable a sensor. In this case, you must send the user to the app settings to manually enable the sensor. 

Sahha.openAppSettings(this@MainActivity)

(iOS) Permission Changes - IMPORTANT INFO

App will terminate if Permission Changes

If the user enables / disables a sensor permission from the device settings menu while your app is in the background, the iOS system will force your app to terminate. This is intentional behavior and your app will need to be relaunched.

Next
Step 7.) Scores