Please check our sample app, that makes full use of the SDK.

1. Introduction

The Vital SDK is split into three main components: VitalClient, VitalHealthConnect and VitalDevices.

  • VitalClient holds common components to both VitalHealthConnect and VitalDevices. Among other things, it has the network layer that allows us to send data from a device to a server.
  • VitalHealthConnect is an abstraction over Health Connect
  • VitalDevices is an abstraction over a set of Bluetooth devices.

2. Installation

You can install the Vital SDK by adding the followings to your build.gradle file:

repositories {
  ...
  maven { url 'https://jitpack.io' }
}
implementation 'com.github.tryVital.vital-android:VitalClient:$vital_version'
implementation 'com.github.tryVital.vital-android:VitalHealthConnect:$vital_version'
implementation 'com.github.tryVital.vital-android:VitalDevices:$vital_version'

Replace $vital_version with the latest version of the SDK. You only need to add the dependencies for the components you want to use.

The min version of the SDK is 21 for VitalClient but for VitalHealthConnect and VitalDevices it is 26.

VitalHealthClient installation

You have no additional steps to take to use VitalHealthClient.

VitalHealthConnect installation

The sdk compiles on min version 26 but to get data out of the underlying Health Connect SDK you need to be on 28 or higher.

You need to update your manifest with the list of requested health permissions.

<activity>
    ...
    <meta-data
        android:name="health_permissions"
        android:resource="@array/health_permissions" />
</activity>

List your required permissions here res/values/health_permissions.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <array name="health_permissions">
        <item>androidx.health.permission.ActivitySession.READ</item>
        <item>androidx.health.permission.Distance.READ</item>
        ...
        <item>androidx.health.permission.BloodPressure.READ</item>
    </array>
</resources>

It is recommended to add the following intent filter to one of your activities to show the rationale for the health permissions:

<activity>
    ...
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
</activity>

VitalDevices installation

Vital Devices uses bluetooth, and it requires different permissions based on you apps min version. Here is an example of a AndroidManifest.xml file that uses Vital Devices:

    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation"/>
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>

    <!-- Request legacy Bluetooth permissions on older devices. -->
    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30"/>

3. Usage

1. VitalClient

First you need to get an instance of VitalClient:

    val client = VitalClient(
    context = this,
    region = Region.EU,
    environment = Environment.Sandbox,
    apiKey = "sk_eu_S5L..." //your key from the dashboard
)

Now you can start using the client to send and receive data from the server.

You can read about the available methods in the docs.

2. VitalHealthConnect

Health Connect is the new unified health data platform from Google. You can read more about it here - https://developer.android.com/guide/health-and-fitness/health-connect Vital Health Connect is an abstraction over Health Connect that allows you to easily and automatically get data from Health Connect and upload it to Vital.

To interact with Vital Health Connect you need an instance of VitalHealthConnectManager:

val vitalHealthConnectManager = VitalHealthConnectManager.create(context, apiKey, region, environment);

You should first check if Health Connect is available on the device:

vitalHealthConnectManager.isAvailable(context)

After you have a user id you need to set it on the manager:

vitalHealthConnectManager.setUserId(userId)

If this user is not yet linked to Health Connect provider you need to link it:

vitalHealthConnectManager.linkUserHealthConnectProvider("callbackUrl")

Now you can start syncing data:

vitalHealthConnectManager.configureHealthConnectClient(
    logsEnabled = false,
    syncOnAppStart = true, //this requires further setup
    numberOfDaysToBackFill = 30,
)

The call to configureHealthConnectClient will start syncing data immediately from Health Connect. You only need to call configure once. If you want to change the configuration you can call it again.

We can only sync health data which we have permission granted by the user. You need to request these permissions. You can see all the used permission in the VitalHealthConnectManager.vitalRequiredPermissions property. You can check what permissions are granted by the user by calling VitalHealthConnectManager.getGrantedPermissions(context).

If you know that you have new data in Health Connect you can force a sync:

vitalHealthConnectManager.syncData()

You can configure the sync to happen on app start. To do this you need to add the following to your manifest:

    <provider
        android:name="androidx.startup.InitializationProvider"
        android:authorities="${applicationId}.androidx-startup"
        android:exported="false"
        tools:node="merge">
        <meta-data  android:name="io.tryvital.vitalhealthconnect.VitalHealthInitializer"
            android:value="androidx.startup" />
    </provider>

Vital Resources types

The mapping between Health Connect resources and Vital resources is as follows:

Vital ResourceHealth Connect Resource
profileHeightRecord,WeightRecord
bodyBodyFatRecord
workoutExerciseSessionRecord
activityActiveCaloriesBurnedRecord,BasalMetabolicRateRecord,StepsRecord,DistanceRecord,FloorsClimbedRecord,Vo2MaxRecord
sleepSleepSessionRecord
glucoseBloodGlucoseRecord
bloodPressureBloodPressureRecord
heartRateHeartRateVariabilitySdnnRecord
stepsStepsRecord
activeEnergyBurnedActiveCaloriesBurnedRecord
basalEnergyBurnedBasalMetabolicRateRecord
waterHydrationRecord

3. VitalDevices

To interact with Vital Devices sdk you need to get an instance of the VitalDeviceManager:

val deviceManager = VitalDeviceManager.create(context)

Next you have to scan for one of the supported devices. You can find the list of supported devices by calling VitalDeviceManagerBrands.devices.

You can search now.

vitalDeviceManager.search(deviceModel).collect { scannedDevice ->
    // scannedDevice is the device that was found of the type deviceModel
}

Depending on the type of device you are connecting to, you will have to call different methods to connect to it.

1. Blood pressure monitor

vitalDeviceManager.bloodPressure(context, scannedDevice)
    .collect { bloodPressureSample ->
        // bloodPressureSample is the sample that was received from the device
    }

2. Glucose meter

vitalDeviceManager.glucoseMeter(context, scannedDevice)
    .collect { glucoseSample ->
        // glucoseSample is the sample that was received from the device
    }

After you have received samples depending on the type of device you might need to star scanning again to receive the next set of samples.