Mobile SDK Installation
Learn about the minimum runtime and build-time requirements of Vital Mobile SDKs, and how to add them into
your project through your package dependency manager.
Vital Health SDK
Learn about the initial setup required by Vital Health SDK, and the API exposed by Vital Health SDK
for managing and inspecting health data permissions and automatic data sync.
Getting Started
To enable this integration, you would need to integrate Vital Core SDK and Vital Health SDK into your Native iOS, React Native or Flutter mobile app.1
Add Vital SDKs as dependencies
2
Integrate with Vital Mobile SDK Authentication
Follow the SDK Authentication guidance to integrate your app with the authentication
mechanism of Vital Core SDK.
3
Configure Health SDK and ask user for read permissions
Follow the Vital Health SDK starting guidance to
configure the Health SDK and to
ask for health data read permissions from your user.
Health data sync is activated only on
VitalResource
s which you have asked permissions from your user for. If you
did not ask for permissions, data sync would not occur.4
[Optional] Customize the Foreground Service notification
Follow the Running as Foreground Service guidance below to
customize the Foreground Service notification which may be shown by the Android OS during
any prolonged health data sync attempts.
5
[Optional] Configure Background Sync
Follow the Background Sync guidance below to
configure regular background sync.
Review the Google Play Store policy
Apps using Android Health Connect require prior Google approval before they can be released on Google Play Store. Check out the official Google Play Store policy on Android Health Connect. Note that the application form is located under the “How do I access data through Health Connect?” section.Configure your AndroidManifest.xml
Health Connect privacy dialogue
Missing manifest declarations may result in Health Connect ignoring your app.
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:
SDK VitalResource type | Read permissions required |
---|---|
Profile | android.permission.health.READ_HEIGHT |
Body | android.permission.health.READ_BODY_FAT android.permission.health.READ_WEIGHT |
Workout | android.permission.health.READ_EXERCISE android.permission.health.READ_HEART_RATE android.permission.health.READ_RESPIRATORY_RATE android.permission.health.READ_DISTANCE android.permission.health.READ_ACTIVE_CALORIES_BURNED android.permission.health.READ_ELEVATION_GAINED android.permission.health.READ_POWER android.permission.health.READ_SPEED |
Activity | android.permission.health.READ_ACTIVE_CALORIES_BURNED android.permission.health.READ_BASAL_METABOLIC_RATE android.permission.health.READ_TOTAL_CALORIES_BURNED android.permission.health.READ_DISTANCE android.permission.health.READ_STEPS android.permission.health.READ_FLOORS_CLIMBED android.permission.health.READ_DISTANCE android.permission.health.READ_VO2_MAX |
Sleep | android.permission.health.READ_SLEEP android.permission.health.READ_HEART_RATE android.permission.health.READ_RESPIRATORY_RATE android.permission.health.READ_HEART_RATE_VARIABILITY android.permission.health.READ_OXYGEN_SATURATION android.permission.health.READ_RESTING_HEART_RATE |
Glucose | android.permission.health.READ_BLOOD_GLUCOSE |
BloodPressure | android.permission.health.READ_BLOOD_PRESSURE |
HeartRate | android.permission.health.READ_HEART_RATE |
Steps | android.permission.health.READ_STEPS |
ActiveEnergyBurned | android.permission.health.READ_ACTIVE_CALORIES_BURNED |
BasalEnergyBurned | android.permission.health.READ_ACTIVE_CALORIES_BURNED android.permission.health.READ_BASAL_METABOLIC_RATE android.permission.health.READ_TOTAL_CALORIES_BURNED |
Water | android.permission.health.READ_HYDRATION |
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 requiredshortService
Foreground Services declarations
into your AndroidManifest.xml. You need not modify your app’s Manifest to enable this.
Vital Health SDK can run work inside the AndroidX WorkManager
foregorund service, as well as our own
SyncOnExactAlarmService
. The merged AndroidManifest.xml of your app
would include both of them.Prepare your app architecture
Incompliance to the guidelines below may result in Health Connect permission flow failing to launch on specific Android OS versions.
- Native Android
- React Native
- Flutter
When requesting permission using the
ActivityResultContract
created by Vital Health createPermissionRequestContract()
, you must launch
the contract using AndroidX Activity Result API.Attempts to launch the contract manually via the legacy Activity.startActivityForResult
API would result in an android.content.ActivityNotFoundException
exception on Android 14 and later.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.Vital Health SDK relies on the AndroidX ProcessLifecycleOwner
to get notified of your app’s resumption.
Running as Foreground Service
You cannot opt-out of this behaviour.
- It ensures ongoing data sync can run to completion even if the user switches away from your app; and
- data sync workers have to be in foreground to read data from Health Connect. Health Connect prohibits reading data from background.
Item | Copy |
---|---|
Notification Title | Health Data Sync |
Notification Content | {APP_NAME} is synchronizing with Health Connect… |
Channel Title | Health Data Sync |
Channel Description | Notifies when {APP_NAME} is synchronizing with Health Connect. |
- Native Android
- React Native
- Flutter
Register your custom An example
SyncNotificationBuilder
through VitalHealthConnectManager.syncNotificationBuilder
.You should register it as soon as your app process is created. One way to ensure this is through the AndroidX Startup
library. You can define an Initializer
of your own that depends on the SDK VitalHealthConnectInitializer
.An example App Startup Initializer implementation
An example SyncNotificationBuilder
implementation
Background Sync
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.Not to be confused with Alarm Clock apps, Exact Alarm is the technical name of an Android framework for scheduling
app wake-ups in background at certain wall clock time. It is the Vital Health SDK being silently “alarmed” in background.Your user will not be alarmed hourly as a result of enabling Background Sync.However, if the data sync took longer than 10 seconds, the OS might nudge them of this occurrence with a user-visible notification.
The notification content is configurable by you — see the “Running as Foreground Service” section for more details.
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:
- 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.
- The user may refuse to grant the “Alarms & Reminders” permission.
- The user may revoke the “Alarms & Reminders” permission through Android Settings at any time.
USE_EXACT_ALARM
permission was introduced. This permits your app to
schedule Exact Alarms without interactive permission requests.
USE_EXACT_ALARM
attracts scrutiny during Google Play Store review. Per the Google Play Exact alarm permission policy:USE_EXACT_ALARM is a restricted permission and apps must only declare this permission if their core functionality supports the need for an exact alarm. Apps that request this restricted permission are subject to review, and those that do not meet the acceptable use case criteria will be disallowed from publishing on Google Play. (excerpted on 20 March 2024)If you choose to incorporate
USE_EXACT_ALARM
, you should prepare to justify to Google Play Store:- Why hourly background sync is quintessential to your product experience; and
- Why the interactive permission request required by
SCHEDULE_EXACT_ALARM
is non-optimal to your product experience.
Android OS | API Level | Requirements |
---|---|---|
Android 11 or below | <=30 | No interactive permission request. |
Android 12 | 31, 32 | SCHEDULE_EXACT_ALARM : Requires a runtime permission request. Revokable. |
Android 13 and above | >=33 | App must declare either:
|
Updating your AndroidManifest.xml
Your app’s AndroidManifest.xml must include the followinguses-permission
claims:
- The SCHEDULE_EXACT_ALARM route
- The USE_EXACT_ALARM route
Make sure you read and understand Runtime User Permission before moving forward.
This option is mutually exclusive with
USE_EXACT_ALARM
in the second tab.Enabling Background Sync
- Native Android
- React Native
- Flutter
You can enable Background Sync through
enableBackgroundSyncContract()
(an AndroidX ActivityResultContract
).If the runtime requires an interactive permission request, this contract will launch
an Android Intent to request the “Alarms & Reminders” permission. The contract result is a boolean, indicating whether
or not the Background Sync has been enabled successfully. For example, if the user did not grant the permission during the said Android Intent,
the contract returns false
.Otherwise, the contract returns true
synchronously when no user interaction is required.You must launch this ActivityResultContract
either through the in-built Android Compose support, or
through the AndroidX Activity Result API if you do not use Android Compose.You can also inspect if Background Sync has been enabled through the isBackgroundSyncEnabled
property.Disabling Background Sync
- Native Android
- React Native
- Flutter
You can disable Background Sync through the
disableBackgroundSync()
method.You can also inspect if Background Sync has been disabled through the isBackgroundSyncEnabled
property.Miscellaneous
When yousignOut()
a user, Vital SDK will automatically disable Background Sync.