Health Sampling Package

Collect health data from Google Health Connect and Apple Health in a CARP Mobile Sensing study.

Copy Markdown

Open in

carp_health_package adds health data from Google Health Connect on Android and Apple Health on iOS to a CARP Mobile Sensing (CAMS) study. It reads what the phone, a wearable or a fitness app has stored, such as steps, heart rate, sleep, weight and workouts. Each data point becomes a measurement.

The package reads the data with the health plugin and exports that plugin. A protocol can ask for any HealthDataType that the plugin supports on the platform.

pub.dev

API reference

GitHub

Foreground only

The package reads health data only while the app is in the foreground, and on iOS only while the phone is unlocked. A failed read loses no data, because the next read covers the same time span. To pick a trigger that fires while the app is in use, see Choose a trigger.

Features

Background collection

Add a health measure to a background task, and a trigger reads the data, for example every hour or each time the app opens.

Health app tasks

A HealthAppTask puts a task on the participant's task list. Starting it asks for access to the data and reads it once.

Incremental reads

The first read goes 30 days back, and each later read continues where the previous one ended, also after an app restart.

Health Connect and Apple Health

One protocol works on both platforms. CAMS skips the data types that a platform does not offer and reads the others.

Measure types

Measure type	Data	Android	iOS
`dk.cachet.carp.health`	One data point of any health data type, such as a step count or a heart rate sample	Yes	Yes

All health data shares this measure type, and the healthDataType field of each measurement names its kind. For the fields, see Health data. For the data types on each platform, see Data types.

Requirements

Component	Requirement
Dart SDK	3.10 or later
Flutter	3.38.1 or later
`carp_mobile_sensing`	2.3.0 or later
Android	API level 26 (Android 8.0) or later, required by the `health` plugin
Android build	`compileSdk` 36 or later and Android Gradle plugin 8.9.1 or later, required by the Health Connect client
Health Connect	Part of Android 14 or later. On Android 13 and earlier, the participant installs the Health Connect app from Google Play.
iOS	15.0 or later, with the HealthKit capability
Health data	Data in Health Connect or Apple Health, from the phone, a wearable or another app

How it works

Each time its trigger fires, a health measure reads the health store in three stages:

flowchart LR
    Trigger["<b>Trigger</b><br/>every hour or when<br/>the app opens"] --> Service["<b>HealthService</b><br/>reads with the<br/>health plugin"]
    Store[("<b>Health store</b><br/>Health Connect or<br/>Apple Health")] --> Service
    Service --> CAMS["<b>CAMS</b><br/>one HealthData<br/>measurement per<br/>data point"]

A trigger in the protocol starts the health measure on the HealthService, a connected device that stands for the health store on the phone.
The health plugin reads the measure's data types from Health Connect or Apple Health, covering the time since the previous read.
Each data point becomes a HealthData measurement, which the study's data manager stores or uploads.

Before the first read, the participant must allow the app to read the data types. To ask for access, see Permissions.

Next steps

Installation

Add the package and configure Health Connect and HealthKit.

Quickstart

Build an app that reads steps and heart rate every hour.

Collecting data

Collect with background measures or health app tasks, and choose triggers.

Permissions

Ask for access to health data and connect the health service.