Android Health Connect

Android Health Connect is an SDK-based provider. Your Android consumer app would embed the Vital Mobile SDKs on a supported stack. Data are then pulled from the Health Connect data store on the user’s Android device.

Refer to the Mobile SDK Installation and Vital Health SDK guides for SDK installation instructions and general API usage. This guide contains information on the the behaviour and required configuration specific to the Android Health Connect integration.

​

Configure your AndroidManifest.xml

​

Health Connect privacy dialogue

Check the Health Connect Getting Started guide for the official requirements.

Here is a minimum declaration example:

<manifest ...>
    <application ...>
        <!-- BEGIN: Mandatory for Health Connect permission flow (Android 13 or below) -->
        <!-- Must either be your MainActivity, or a separate Activity; cannot be an activity-alias. -->
        <activity android:name=".MainActivity" ...>
            <intent-filter>
                <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
            </intent-filter>
        </activity>
        <!-- END -->

        <!-- BEGIN: Mandatory for Health Connect permission flow (Android 14 or above) -->
        <!-- Can be an activity or an activity-alias. -->
        <activity-alias
            android:name="ViewPermissionUsageActivity"
            android:exported="true"
            android:targetActivity=".MainActivity"
            android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
            <intent-filter>
                <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
                <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
            </intent-filter>
        </activity-alias>
        <!-- END -->
    </application>

    <queries>
        <package android:name="com.google.android.apps.healthdata" />
    </queries>
</manifest>

​

Health Connect permissions

Your app manifest (AndroidManifest.xml) must declare all the read or write permissions for all the data types you intend to sync.

For example, if you intend to sync Blood Pressure records and Blood Glucose reocrds, your app manifest must contain the following <uses-permission> declarations:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <!-- ... other declarations -->

    <!-- BEGIN: Health Connect permissions -->
    <uses-permission android:name="android.permission.health.READ_BLOOD_GLUCOSE" />
    <uses-permission android:name="android.permission.health.READ_BLOOD_PRESSURE" />
    <!-- END: Health Connect permissions -->
</manifest>

​

Foreground Service permissions

Vital Health SDK runs all its data sync workers inside a short-service Foreground Services.

At build time, Vital Health SDK injects all the required shortService Foreground Services declarations into your AndroidManifest.xml. You need not modify your app’s Manifest to enable this.

​

Prepare your app architecture

• Native Android
• React Native
• Flutter

​

Synchronization

​

Sync On App Launch

When your app resumes from background (i.e., having no Activity), Vital Health SDK triggers a data sync on all the resources to which the user has granted read permission.

The SDK imposes a 2-minute throttle on automatic data sync. This is to prevent rapid app switching from causing an excessive amount of data sync work being scheduled.

​

Running as Foreground Service

Vital Health SDK runs all its data sync workers inside a Foreground Service. Running as a foreground service helps in two ways:

1. It ensures ongoing data sync can run to completion even if the user switches away from your app; and

2. data sync workers have to be in foreground to read data from Health Connect. Health Connect prohibits reading data from background.

Android requires every Foreground Service to be associated with a user-visible notification. The OS typically grants a grace period of about 10 seconds before making the user aware of this notification. In other words, if the data sync worker completes within the grace period, no notification would be posted.

Vital Health SDK installs these notification copies by default:

You can customize it through two ways:

• Native Android
• React Native
• Flutter

package com.example.app

import android.content.Context
import androidx.startup.Initializer
import io.tryvital.vitalhealthconnect.VitalHealthConnectManager
import io.tryvital.vitalhealthconnect.VitalHealthConnectInitializer

class ExampleSyncNotificationBuilderInitializer: Initializer<Unit> {
    override fun create(context: Context) {
        val manager = VitalHealthConnectManager.getOrCreate(context)
        manager.syncNotificationBuilder = ExampleSyncNotificationBuilder
    }

    override fun dependencies(): MutableList<Class<out Initializer<*>>> = mutableListOf(
        VitalHealthConnectInitializer::class.java,
    )
}

package io.tryvital.sample

import android.app.Notification
import android.app.NotificationChannel
import android.app.NotificationManager
import android.content.Context
import android.content.Context.NOTIFICATION_SERVICE
import androidx.core.app.NotificationCompat
import io.tryvital.vitalhealthconnect.SyncNotificationBuilder
import io.tryvital.vitalhealthconnect.model.VitalResource

object ExampleSyncNotificationBuilder: SyncNotificationBuilder {
    override fun build(context: Context, resources: Set<VitalResource>): Notification {
        return NotificationCompat.Builder(context, createChannel(context))
            .setContentTitle("Example Sync")
            .setContentText("Syncing your data")
            .setOngoing(true)
            .setSmallIcon(android.R.drawable.ic_popup_sync)
            .build()
    }

    fun createChannel(context: Context): String {
        val importance = NotificationManager.IMPORTANCE_MIN
        val mChannel = NotificationChannel("ExampleSyncNotification", "Example Sync", importance)
        mChannel.description = "Notifies when Example is syncing your data"
        val notificationManager = context.getSystemService(NOTIFICATION_SERVICE) as NotificationManager
        notificationManager.createNotificationChannel(mChannel)
        return mChannel.id
    }
}

​

Background Sync (Experimental)

Vital Health SDK supports an opt-in Android Background Sync feature. It provides a continuous monitoring experience with Android Health Connect, siimlar to Background Delivery for Apple HealthKit on iOS.

​

Sync Frequency

The Sync On App Launch behaviour is always-on.

When Background Sync is enabled, the SDK additionally schedules hourly sync using the Android Exact Alarms mechanism.

The OS has full discretion on whether to honour or defer the time as scheduled by the Vital Health SDK. This includes the policies of the base Android OS, as well as any vendor-specific OS augmentation.

For example, the device may enter Doze mode during device inactivity. Doze mode would batch and defer most Exact Alarms and other background work to run at a lower frequency.

​

Runtime Permission Request

Since Android 12 (API Level 31), scheduling Exact Alarm (SCHEDULE_EXACT_ALARM) requires a runtime permission request from the user. More specifically:

1. The user must go through an interactive flow to grant the “Alarms & Reminders” permission.
   • This flow is also reachable through the “Alarms & Reminders” section in Android Settings.
2. The user may refuse to grant the “Alarms & Reminders” permission.
3. The user may revoke the “Alarms & Reminders” permission through Android Settings at any time.

Since Android 13 (API Level 33), a new mutually exclusive USE_EXACT_ALARM permission was introduced. This permits your app to schedule Exact Alarms without interactive permission requests.

Here is a matrix summarizing the Exact Alarm permission request requirements:

​

Updating your AndroidManifest.xml

Your app’s AndroidManifest.xml must include the following uses-permission claims:

• The SCHEDULE_EXACT_ALARM route
• The USE_EXACT_ALARM route

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>

    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />

</manifest>

​

Enabling Background Sync

• Native Android
• React Native
• Flutter

import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.material3.*
import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

val manager: VitalHealthConnectManager = ...

val permissionsLauncher = rememberLauncherForActivityResult(
    manager.enableBackgroundSyncContract()
) { success ->
    Log.i("VitalBackgroundSync", "Enabled? $success")

    val enabled = manager.isBackgroundSyncEnabled
    Log.i("VitalBackgroundSync", "Enabled? $enabled")
}

Button(onClick = { permissionsLauncher.launch(Unit) }) {
    Text("Enable Background Sync")
}

​

Disabling Background Sync

• Native Android
• React Native
• Flutter

import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

val manager: VitalHealthConnectManager = ...
manager.disableBackgroundSync()

val enabled = manager.isBackgroundSyncEnabled
Log.i("VitalBackgroundSync", "Enabled? $enabled")

​

Miscellaneous

When you signOut() a user, Vital SDK will automatically disable Background Sync.