Integrate the Neurofit Vitals SDK into Your Android App

The Neurofit Vitals SDK brings a fully on-device 60-second rear-camera scan to your Android app, measuring heart rate, HRV, and respiration rate without sending any data to external servers. This guide covers everything from Gradle setup to handling your first VitalsResult with the Activity Result API.

Add the Maven repository and SDK dependency

Declare the Neurofit Maven repository in your project-level settings.gradle.kts so Gradle knows where to resolve the artifact. Then add the implementation dependency to your app module’s build.gradle.kts.

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://sdk.neurofit.app/vitals-android") }
    }
}

build.gradle.kts (app module)

dependencies {
    implementation("app.neurofit:vitals-sdk:1.0.0")
}

Sync your Gradle project after making these changes. The SDK is under 1 MB and introduces no additional analytics or tracking dependencies.

If your project still uses Groovy-based .gradle files, replace url = uri(...) with url "https://sdk.neurofit.app/vitals-android" and use single-quote strings for the dependency coordinate.

Add permissions to AndroidManifest.xml

The SDK requires camera hardware to capture the photoplethysmography signal. Add both the CAMERA permission and the camera hardware feature declaration to your AndroidManifest.xml. Marking the feature as required="true" prevents the app from being installed on devices that lack a rear camera.

AndroidManifest.xml

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature
    android:name="android.hardware.camera"
    android:required="true" />

CAMERA is a dangerous permission — you must request it at runtime on API 23 and above. VitalsScanActivity requests the permission automatically before opening the camera, but your app should be prepared to handle the CAMERA_PERMISSION_DENIED exception if the user denies or permanently dismisses the dialog.

Initialize the SDK in Application.onCreate()

Call VitalsSDK.configure once during application startup so the license is validated before any scan is launched. The Application subclass is the recommended location. Register it in your manifest with android:name=".MyApplication".

MyApplication.kt

import android.app.Application
import android.graphics.Color
import app.neurofit.vitals.VitalsSDK
import app.neurofit.vitals.VitalsSDKConfiguration
import java.util.Locale

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        VitalsSDK.configure(
            context = this,
            licenseKey = "YOUR_LICENSE_KEY",
            configuration = VitalsSDKConfiguration(
                locale = Locale.getDefault(),
                accentColor = Color.parseColor("#1f1f1f"),
                enableHaptics = true
            )
        )
    }
}

Keep your license key out of source control. Store it in local.properties or retrieve it from Android Keystore / EncryptedSharedPreferences at runtime. Reference it in build.gradle.kts via BuildConfig fields rather than hardcoding the string.

Launch VitalsScanActivity

The SDK ships VitalsScanActivity, which owns the full scan UI including finger placement guidance, countdown, and quality feedback. The recommended approach is the Activity Result API introduced in AndroidX Activity 1.2.

Activity Result API (recommended)
startActivityForResult (legacy)

Register the contract once at class level, then call launch whenever you want to start a scan. The lambda receives a nullable VitalsResult — it is null only if the activity was cancelled before completion.

MainActivity.kt

import app.neurofit.vitals.VitalsScanContract
import app.neurofit.vitals.VitalsResult

private val scanLauncher = registerForActivityResult(
    VitalsScanContract()
) { result: VitalsResult? ->
    result?.let { handleVitalsResult(it) }
}

// Call this from a button click or wherever you want to start the scan
fun startScan() {
    scanLauncher.launch(Unit)
}

If your codebase has not yet migrated to the Activity Result API, the legacy approach remains supported. Note that onActivityResult is deprecated in newer AndroidX versions.

Legacy approach

import app.neurofit.vitals.VitalsScanActivity

private val VITALS_SCAN_REQUEST_CODE = 1001

fun startScan() {
    val intent = VitalsScanActivity.createIntent(this)
    startActivityForResult(intent, VITALS_SCAN_REQUEST_CODE)
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == VITALS_SCAN_REQUEST_CODE && resultCode == RESULT_OK) {
        val result = VitalsScanActivity.getResult(data)
        result?.let { handleVitalsResult(it) }
    }
}

Handle scan results

After a successful scan, check qualityTier before accessing any metric fields. A WITHHELD result means the signal was too noisy or unstable to produce a reliable reading — surface a retry prompt rather than displaying partial numbers.

Result handling

import app.neurofit.vitals.QualityTier
import app.neurofit.vitals.VitalsResult

private fun handleVitalsResult(result: VitalsResult) {
    if (result.qualityTier == QualityTier.ACCEPTED) {
        Log.d("Vitals", "HR: ${result.heartRate} bpm")
        Log.d("Vitals", "RMSSD: ${result.rmssd} ms")
        Log.d("Vitals", "SDNN: ${result.sdnn} ms")
        Log.d("Vitals", "Baevsky: ${result.baevsky}")
        Log.d("Vitals", "Poincaré SD2:SD1: ${result.poincareSD2SD1}")
        result.breathingRate?.let { Log.d("Vitals", "Breathing: $it bpm") }
    } else {
        // QualityTier.WITHHELD — metric fields are not populated
        showRetryPrompt()
    }
}

breathingRate may be null even in ACCEPTED readings when the breathing signal did not reach the confidence threshold. Treat null as “not available this scan” rather than an error, and avoid displaying a placeholder value.

Handle exceptions and edge cases

VitalsException is thrown (or delivered via the result callback) when the SDK encounters an unrecoverable condition. The three exception types and their recommended handling are described below.

CAMERA_PERMISSION_DENIED

The user denied the runtime camera permission. Display a rationale dialog and direct the user to Settings → Apps → [Your App] → Permissions to grant access. Use ActivityCompat.shouldShowRequestPermissionRationale to decide whether to show the rationale.

LICENSE_INVALID

The license key failed on-device validation. Confirm the key value in your Neurofit developer dashboard and verify it is being read correctly from your build configuration. This error cannot be recovered at runtime without a valid license key.

SCAN_INTERRUPTED

The scan was stopped before completion — for example, because the app was sent to the background or a system interruption (such as a phone call) occurred. You can offer an immediate retry without any additional reset step.

UNKNOWN

An unexpected condition occurred that does not map to any of the named exception types. Log the exception for diagnostics and surface a generic failure message to the user. If this exception occurs consistently, contact support@neurofit.app with your SDK version and reproduction steps.

The Neurofit Vitals SDK requires Android API 24 (Android 7.0 Nougat) or higher. Set minSdk = 24 in your app module’s build.gradle.kts if it is not already at that level.

The rear camera is required and must be tested on a physical Android device. Emulators do not provide a real camera stream and will trigger a CAMERA_PERMISSION_DENIED or SCAN_INTERRUPTED exception when the SDK tries to access the sensor.

Overview

Getting Started

Integration Guide

Metrics Reference

Help

Integrate the Neurofit Vitals SDK into Your Android App