This guide shows you how you can start using the Health Connect API on your app.
Resources
Before you begin, you can check out the following resources that help with development later on.
- Health Connect SDK (available on Jetpack). Include this SDK in your application to use the Health Connect API.
- API reference. Take a look at the Jetpack reference for the Health Connect API.
- API Request Developer Declaration Form. Use this form to request access to read and write data types.
- Optional: Github code sample and codelab. See the Github code sample repository and the codelab to help you get started.
Step 1: Install Health Connect
Install Health Connect by Android from the Google Play Store to your device. It handles all requests sent by your application using the Health Connect SDK.
After installation
Health Connect no longer appears on the Home screen by default. To open Health Connect, go to Settings > Apps > Health Connect or add Health Connect to your Quick Settings menu.
To add, Health Connect requires the user to have screen lock enabled with a PIN, pattern, or password so that the health data being stored in Health Connect is protected from malicious parties while the device is locked. To set a screen lock, go to Settings > Security > Screen lock.
Step 2: Add the Health Connect SDK to your application
Add a dependency on the Health Connect SDK in your module-level build.gradle
file:
dependencies {
...
implementation "androidx.health.connect:connect-client:1.0.0-alpha11"
...
}
Refer to the Health Connect releases for the latest version.
Step 3: Get Health Connect client
HealthConnectClient
is an entry point to the Health Connect API.
This step explains the process of integrating the app with Health Connect to use its features.
Declare the Health Connect package name in your
AndroidManifest.xml
file.<!-- Check whether Health Connect is installed or not --> <queries> <package android:name="com.google.android.apps.healthdata" /> </queries>
Check if Health Connect is installed. If it is, obtain a
HealthConnectClient
instance.If you are using
alpha11
or higher versions, usesdkStatus
. The following example shows how to check if the SDK is available, if it needs updates, or if it is unavailable.val availabilityStatus = HealthConnectClient.sdkStatus(context, providerPackageName) if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) { return // early return as there is no viable integration } if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) { // Optionally redirect to package installer to find a provider, for example: val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding" context.startActivity( Intent(Intent.ACTION_VIEW).apply { setPackage("com.android.vending") data = Uri.parse(uriString) putExtra("overlay", true) putExtra("callerId", context.packageName) } ) return } val healthConnectClient = HealthConnectClient.getOrCreate(context) // Issue operations with healthConnectClient
If you are using versions between
alpha08
andalpha10
, useisProviderAvailable
. The following example shows how to implement it.if (HealthConnectClient.isProviderAvailable(context)) { // Health Connect is available and installed. val healthConnectClient = HealthConnectClient.getOrCreate(context) } else { // ... }
The client app must request permission from the user. The user can grant or deny access to the client app at any point.
HealthConnectClient
automatically manages its connection to the
underlying storage layer and handles all IPC and serialization of outgoing
requests and incoming responses.
Step 4: Declare permissions
Every data type your app reads or writes needs to be declared using a permission in your manifest. In this step, the configuration differs depending on which SDK version you use.
For more information about how permissions are managed, prompted, requested, declared, and revoked in Health Connect, see Managing permissions in Health Connect.
For 'alpha10' and higher versions
On versions alpha10
and higher, Health Connect uses the standard Android
permission declaration format.
To declare the permissions for the required data types, use the
<uses-permission>
tags and assign their respective names with the permissions. Nest them within the<manifest>
tags.<manifest> <uses-permission android:name="android.permission.health.READ_HEART_RATE"/> <uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/> <uses-permission android:name="android.permission.health.READ_STEPS"/> <uses-permission android:name="android.permission.health.WRITE_STEPS"/> <application> ... </application> </manifest>
For the full list of permissions and their corresponding data types, see List of data types.
Explain how your app uses Health Connect.
Your manifest needs to provide
<activity>
which displays the privacy policy describing how the user's data is used and handled. You can either add a new<activity>
or modify an existing one.This activity needs to declare that it handles the
ACTION_SHOW_PERMISSIONS_RATIONALE
intent. This intent is sent to the app when the user clicks on the Read privacy policy link in the Health Connect permissions dialog.... <uses-permission android:name="android.permission.health.READ_HEART_RATE"/> <uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/> <uses-permission android:name="android.permission.health.READ_STEPS"/> <uses-permission android:name="android.permission.health.WRITE_STEPS"/> <application> ... <!-- Activity to show rationale of Health Connect permissions --> <activity android:name=".PermissionsRationaleActivity" android:exported="true" android:enabled="true"> <!-- Handle intent --> <intent-filter> <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" /> </intent-filter> </activity> ... </application> ...
For 'alpha09' and lower versions
On versions alpha09
and lower, Health Connect uses a list of values from the
resources folder containing the health permissions.
To declare the permissions for the data types required, create an array resource in
res/values
.<resources> <array name="health_permissions"> <item>androidx.health.permission.HeartRate.READ</item> <item>androidx.health.permission.HeartRate.WRITE</item> <item>androidx.health.permission.Steps.READ</item> <item>androidx.health.permission.Steps.WRITE</item> </array> </resources>
For the full list of permissions and their corresponding data types, see List of data types.
Explain how your app uses Health Connect.
Your manifest needs to provide
<activity>
which displays the privacy policy describing how the user's data is used and handled. You can either add a new<activity>
or modify an existing one.This activity needs to reference the array resource you created to declare the set of permissions. Then, declare that it handles the
ACTION_SHOW_PERMISSIONS_RATIONALE
intent. This intent is sent to the app when the user clicks on the Read privacy policy link in the Health Connect permissions dialog.<application> ... <!-- Activity to show rationale of Health Connect permissions --> <activity android:name=".PermissionsRationaleActivity" android:exported="true" android:enabled="true"> <!-- For alpha09 and lower, reference permissions resource --> <meta-data android:name="health_permissions" android:resource="@array/health_permissions" /> <!-- Handle intent --> <intent-filter> <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" /> </intent-filter> </activity> ... </application>
Hide Health Connect integration
When the Activity that exposes ACTION_SHOW_PERMISSIONS_RATIONALE
is enabled,
your app automatically appears in Health Connect as available. However, there
are some scenarios where you need to hide the Health Connect integration until
it is ready for launch.
In order to hide the integration, set the enabled
attribute of that Activity
to false
.
<activity
android:name=".PermissionsRationaleActivity"
android:exported="true"
android:enabled="false">
...
</activity>
When you're ready to turn it on, dynamically enable it in your app using
PackageManager.setComponentEnabledSetting
.
Step 5: Request permissions from the user
This step explains how to display the permission dialog.
Build a set of permissions for the required data types. Ensure that the permissions in the set are declared in your manifest first.
The manner of building the permission set differs depending on the SDK version used.
For
alpha10
and higher versions:// build a set of permissions for required data types // Each permission value is a string data type val PERMISSIONS = setOf( HealthPermission.getReadPermission(HeartRateRecord::class), HealthPermission.getWritePermission(HeartRateRecord::class), HealthPermission.getReadPermission(StepsRecord::class), HealthPermission.getWritePermission(StepsRecord::class) )
For
alpha09
and lower versions:// build a set of permissions for required data types // Each permission value is a string data type val PERMISSIONS = setOf( HealthPermission.createReadPermission(HeartRateRecord::class), HealthPermission.createWritePermission(HeartRateRecord::class), HealthPermission.createReadPermission(StepsRecord::class), HealthPermission.createWritePermission(StepsRecord::class) )
Use
getGrantedPermissions()
to see if your app already has the required permissions. If not, use thecreateRequestPermissionResultContract()
method to request permission.// Create the permissions launcher. val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract() val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted -> if (granted.containsAll(PERMISSIONS)) { // Permissions successfully granted // PERMISSIONS: Set<string> as of Alpha11 } else { // Lack of required permissions } } suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) { // For alpha09 and lower versions, use getGrantedPermissions(PERMISSIONS) instead val granted = healthConnectClient.permissionController.getGrantedPermissions() if (granted.containsAll(PERMISSIONS)) { // Permissions already granted; proceed with inserting or reading data. } else { requestPermissions.launch(PERMISSIONS) } }
If the user declines your permission request twice, your app is permanently locked out and it cannot request permissions again. If this happens to your app during development and testing, you can reset the permission request count with these steps:
- Open the Health Connect app.
- Go to App permissions.
- Choose your app.
- Toggle Allow all.
- Toggle Allow all again to remove all permissions.
- When the prompt appears, choose Remove all.
Alternatively use adb
to clear the cache of the Health Connect package.
Users can grant or revoke permissions using the Health Connect app at any time. Don't assume that the set of granted permissions does not change. Your app needs to periodically check for granted permissions, and handle scenarios where permission is unexpectedly lost.
Health data is sensitive. To maintain user trust, only request permission to access data in context. Don't request data that your app doesn't use.
Next steps
Watch these two videos that explain how to read and write data in Health Connect, and some best practice guidelines for achieving a smooth integration:
Check out the common workflows for examples on how to perform CRUD operations in Health Connect, such as writing and reading health data.