Synheart Core - Android/Kotlin SDK - Synheart Documentation

What this SDK does

Synheart Core connects an Android app to the native Synheart Runtime. It:

collects user-consented wearable, phone, and behavior signals;
sends those signals to the on-device runtime;
exposes Human State Interface (HSI) 1.3 output as Kotlin Flows;
optionally stores, synchronizes, and uploads derived state.

The Kotlin library handles platform concerns only: Health Connect and BLE collection, Android Keystore, EncryptedSharedPreferences, Flow streams, and Jetpack integration. Human-state computation, storage, device authentication, and sync run in the separately installed native runtime.

HSI is the public output. Most applications should use Synheart.onStateUpdate for typed values or Synheart.onHSIUpdate for the canonical JSON. Internal HSV types do not cross the public SDK boundary.

Requirements


`minSdk`	26
`compileSdk`	35
Java / Kotlin JVM target	17
Core library desugaring	Required
Native runtime	Provisioned by the Synheart CLI, not bundled in the AAR

The library module declares minSdk 24, but it depends on ai.synheart:syni, whose manifest declares 26. A library never runs the full manifest merge, so the conflict appears only when an application builds against it. Set your app to 26.

Installation

1. Add the dependency

dependencies {
    implementation 'ai.synheart:synheart-core:0.2.0'
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4'
}

android {
    defaultConfig {
        minSdk 26
    }
    compileOptions {
        coreLibraryDesugaringEnabled true
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

2. Install the native runtime

The library alone loads no runtime and produces no HSI. Install and authenticate the CLI once, then provision the runtime from your application root:

curl -fsSL https://synheart.sh/install | sh
synheart login
synheart install runtime

Commit the generated synheart.lock, which pins each artifact by SHA-256. Other developers and CI restore the pinned artifacts with synheart sync. The CLI writes the binaries to <app-module>/synheart/vendor/runtime/android/jniLibs/<abi>/. AGP reads only src/main/jniLibs, so point your module at the vendored path:

android {
    sourceSets {
        main {
            jniLibs.srcDirs = [
                project.findProperty('synheart.runtime.android.jniLibs')
                    ?: new File(projectDir, 'synheart/vendor/runtime/android/jniLibs')
                        .absolutePath
            ]
        }
    }
}

Without the jniLibs.srcDirs entry the APK builds cleanly and ships no runtime. Every FFI call then degrades to “native library not loaded” with no build-time error.

3. Declare permissions

Declare only the permissions required by the sources you enable:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

<!-- Health Connect examples -->
<uses-permission android:name="android.permission.health.READ_HEART_RATE" />
<uses-permission android:name="android.permission.health.READ_HEART_RATE_VARIABILITY" />
<uses-permission android:name="android.permission.health.READ_STEPS" />

Health Connect also requires package queries, a permission-rationale intent filter, and a permission-usage activity alias. Copy the applicable declarations from the example manifest.

4. Verify before writing integration code

println(Synheart.isRuntimeAvailable)                          // true once the bridge loaded
println(Synheart.runtimeDiagnostics()?.opt("missingSymbols"))  // empty on a matching runtime

isRuntimeAvailable == false means the library was not bundled. A non-empty missingSymbols means the runtime loaded but predates this SDK release, so the features behind those symbols return null or false rather than throwing.

Start here

The minimum integration has five steps:

Initialize the SDK.
Ask the user for consent.
Subscribe to HSI output.
Start a collection session.
Stop the session and release resources.

import ai.synheart.core.Synheart
import ai.synheart.core.config.SynheartConfig
import ai.synheart.core.config.WearConfig
import ai.synheart.core.config.BehaviorConfig

lifecycleScope.launch {
    Synheart.initialize(
        context = applicationContext,
        config = SynheartConfig(
            appId = "com.example.app",
            subjectId = "user-123",
            appVersion = "1.0.0",
            allowUnsignedCapabilities = true, // Development only.
            wearConfig = WearConfig(),
            behaviorConfig = BehaviorConfig(),
        ),
    )

    Synheart.grantConsent("biosignals")
    Synheart.grantConsent("behavior")

    launch {
        Synheart.onStateUpdate.collect { state ->
            println("Focus: ${state.hsi.focus?.value}")
            println("Arousal: ${state.hsi.arousal?.value}")
        }
    }

    Synheart.startSession()
}

// When finished:
lifecycleScope.launch {
    Synheart.stopSession()
    Synheart.dispose()
}

allowUnsignedCapabilities = true bypasses production capability verification. Never enable it in a release build.

Initialization

SynheartConfig.validate() requires a non-empty appId, a non-empty subjectId, a subjectId without |, and PrivacyConfig(allowResearch = true) when using research mode. It throws SynheartCoreError before the runtime is touched. subjectId is the identity everything attaches to — HSI uploads, baselines, consent tokens, device identity. A value that changes per launch looks like a new person every time and baselines never mature. Passing userId to initialize() does not populate it; set it on the config. initialize() is idempotent: a second call returns without throwing. Guard with Synheart.isInitialized if you need to know. It does not start collection — call startSession() once consent is ready, or pass autoStart = true when consent is already complete.

Modes

Mode	Persistence
`SynheartMode.PERSONAL`	HSI, session summaries, and baselines
`SynheartMode.INSIGHT`	Personal-mode data plus application metrics
`SynheartMode.RESEARCH`	Can include raw bio streams; requires explicit privacy configuration and consent

When the signed-in identity changes, keep the runtime identity aligned without reinitializing:

val changed = Synheart.rebindSubjectId("new-subject-id")

Running without cloud credentials

The SDK is usable with no platform account. Omit CloudConfig and DeviceAuthConfig, and everything on-device works: collection, HSI computation, consent, local storage, and baselines. Nothing leaves the device and no attestation is attempted. HSI upload, cross-device sync, research-study enrolment, and server-issued capability tokens are unavailable in this configuration. Consent and capability are different:

Capability says what the application is authorized to use.
Consent says what the user allows.

Channels are named with camelCase wire strings: biosignals, behavior, phoneContext (motion is a long-standing alias), cloudUpload, vendorSync, research, syni, focusEstimation, and emotionEstimation. The runtime keys the same channels in snake_case; the SDK translates.

Synheart.grantConsent("biosignals")
Synheart.grantConsent("cloudUpload")   // mints a consent token as a side effect

Synheart.revokeConsent("behavior")

Synheart.consentChanges.collect { snapshot ->
    println("Cloud upload allowed: ${snapshot.cloudUpload}")
}

Or install your own consent screen and let the SDK apply the profile the user picks — it ships none of its own:

Synheart.setConsentUIProvider { profiles -> showYourConsentSheet(profiles) }
Synheart.requestConsent()

hasConsent() reports whether a channel is enforceable right now, not what the user chose. Once a cloud consent client is configured, the runtime denies every channel until the consent service issues a token. Gate uploads with hasConsent(); render UI from consentEffectiveStateTyped().

A missing default consent profile on the platform app is the most common cause of “consent is on but nothing uploads”. See Consent System for profiles and JWT lifecycle.

Feature activation and sessions

A feature collects data only when all four of these hold:

operational = activated && consented && capability-allowed && session-running

Authority	Set by	Read with
Activated	a module config, or `activate(feature)`	`isActivated(feature)`
Consented	`grantConsent(type)`	`hasConsent(type)`
Capability allowed	the capability token, or `allowUnsignedCapabilities`	—
Session running	`startSession()`	`isSessionRunning`

Miss one and the feature stays silent — there is no error, because none of these is a failure. Synheart.isFeatureOperational(feature) collapses all four into one answer; check it first when data is not arriving. Declaring wearConfig, phoneConfig, or behaviorConfig activates that feature. Features may also be activated explicitly:

Synheart.activate(SynheartFeature.WEAR)
Synheart.deactivate(SynheartFeature.CLOUD)

Feature	Purpose	Consent
`WEAR`	Wearable biosignals	`biosignals`
`BEHAVIOR`	Interaction timing and patterns	`behavior`
`PHONE_CONTEXT`	Motion, screen, and app context	`motion`
`CLOUD`	HSI cloud upload	`cloudUpload`
`SYNI`	Adaptive AI integration	`syni`

Activation is intersected with deviceRole.supportedFeatures, so a DeviceRole.WATCH build cannot activate behavior or phone context even if the config declares them. A host that declares none of the three module configs collects nothing.

Start and stop the full lifecycle with startSession() / stopSession(), or control individual collectors:

Synheart.startWearCollection()
Synheart.startBehaviorCollection()
Synheart.startPhoneCollection()

Module-level methods still enforce consent and capability gates.

Reading HSI

Typed state

Synheart.onStateUpdate.collect { state ->
    val focus = state.hsi.focus
    val stress = state.hsi.stress

    if (focus != null) println("Focus ${focus.value}, confidence ${focus.confidence}")
    if (stress != null) println("Stress ${stress.value}, confidence ${stress.confidence}")
}

HSIState carries subjectId, timestampMs, hsi, modalities, tiers, rawJson, and parseError. The axes are the five physiological and fused ones (focus, arousal, capacity, sleep, stress) plus three digital ones (focusQuality, interruptionPressure, interactionMode). Axis values are null when there is not enough input. Missing means unknown; it does not mean zero. On a phone with no biosignal source the canonical axes arrive at confidence: 0 — expected, not a fault. Use state.modalities to tell “nothing was collected” from “signal arrived, just not physiological”, and HSIAxes.hasDigital to check whether the window carried a digital axis. Synheart.currentHSIState reuses the same parse, so it is cheap to read repeatedly.

Canonical JSON

Synheart.onHSIUpdate.collect { hsiJson -> sendToYourConsumer(hsiJson) }

Synheart.currentState and HSIState.rawJson hold the same JSON. See HSI in Synheart Core for mapping details.

Raw source streams

Synheart.wearSampleStream.collect { sample -> println("HR: ${sample.hr}") }
Synheart.behaviorEventStream.collect { event -> println("${event.type} at ${event.timestamp}") }

Raw streams are consent-gated. Collect them in a lifecycle-aware scope.

Behavior capture

Android has no view-tree hook, so the SDK ships no gesture detector: nothing is observed unless the host forwards its touches.

override fun dispatchTouchEvent(ev: MotionEvent): Boolean {
    Synheart.recordTouchEvent(ev)
    return super.dispatchTouchEvent(ev)
}

recordTouchEvent derives taps and scrolls, including the part that is easy to get wrong: recording per ACTION_MOVE floods the aggregator. Interaction alone produces the HSI digital axes, so behavior works on hardware with no wearable.

Wearable permissions

Health Connect gates reads behind a runtime prompt, so a manifest declaration alone leaves the source polling an empty store — every sample arrives carrying nothing, which is indistinguishable from a paired-but-silent wearable.

if (!Synheart.hasWearPermissions) {
    val granted = Synheart.requestWearPermissions()   // Map<String, Boolean>
    if (granted.values.none { it }) {
        Synheart.openHealthPermissionSettings(context)
    }
}

println(Synheart.hasWearSource)   // false when no wearConfig was declared

Watch sessions

Added in 0.2.0. The phone drives a session on a paired Wear OS watch over the Wearable Data Layer; the watch owns the session and computes the metrics. Watch heart rate is forwarded into the runtime, so HSI has physiology on a phone with no sensor of its own.

val status = Synheart.getWatchStatus()   // null before initialize()
if (status?.canStartSession == true) {
    Synheart.startWatchSession(
        SessionConfig(
            sessionId = "watch_${System.currentTimeMillis()}",
            mode = SessionMode.FOCUS,
            durationSec = 10 * 60,
        ),
    )
}

Synheart.watchSessionEvents.collect { event -> render(event) }

println(Synheart.isWatchSessionActive)
println(Synheart.watchHrSampleCount)   // engine-bound samples, counted separately

Synheart.stopWatchSession()

Session types come from ai.synheart:synheart-session, which this SDK re-exports. Subscribe to watchSessionEvents before sending the start command so the watch’s first event cannot arrive before anything is listening.

A WatchStatus(supported = false) means the device has no watch transport at all; a null status means the SDK was never initialized. The companion app must share the phone app’s applicationId and signature — the Data Layer delivers only between apps that match on both.

For the watch-to-phone artifact contract, see Edge.

Production device authentication

SynheartConfig(
    appId = "com.example.app",
    subjectId = "user-123",
    deviceAuthConfig = DeviceAuthConfig(
        authBaseUrl = "https://api.synheart.ai",
        packageName = "com.example.app",
    ),
    cloudConfig = CloudConfig(
        subjectId = "user-123",
        orgId = "organization-id",
        instanceId = "stable-installation-uuid",
    ),
)

The runtime registers a hardware-backed ECDSA identity in the Android Keystore and signs supported requests. No shared secret is required.

DeviceAuthConfig.packageName is the installed bundle id, which Play Integrity verifies against. It is not SynheartConfig.appId, the platform-issued application identifier. Passing the latter fails attestation.

Registration is triggered by cloud-upload consent, not by initialize():

val registered = Synheart.ensureDeviceAuthRegistered()
val status = Synheart.coreDeviceAuthStatus()

Use reregisterDeviceAuth() as an explicit repair action when the server has lost or revoked an otherwise valid local identity. See Synheart Auth for the device-identity flow.

Endpoints

The SDK ships no built-in API host — a host baked into the library becomes the destination for any build that forgot to name one, including forks and self-hosted deployments. Resolution order, first non-empty wins:

ApiEndpoints.baseUrlOverride and the per-service overrides
the synheart.baseUrl system property
the SYNHEART_BASE_URL environment variable

ApiEndpoints.baseUrlOverride = BuildConfig.SYNHEART_BASE_URL

With none set, no origin is passed to the runtime and the runtime applies its own default — correct for a local-only build, which makes no network calls at all. Check apiBaseUrlConfigured(config) before enabling anything cloud-bound.

Prefer setting the one base URL over a per-service override. Overriding auth alone points device registration at one environment while consent and ingest stay on another, which surfaces as authentication failures with no obvious cause.

The values must be origins. The runtime appends service paths.

Cloud upload

Cloud upload requires CloudConfig with an orgId, DeviceAuthConfig in production, cloudUpload consent, an issued consent token, and a registered device. The runtime then uploads on its own cadence; no host code moves data.

when (Synheart.cloudSyncStatus) {
    CloudSyncStatus.LOCAL_ONLY -> "Nothing leaves the device"
    CloudSyncStatus.SYNCING    -> "Uploading…"
    CloudSyncStatus.SYNCED     -> "Up to date"
    CloudSyncStatus.PENDING    -> "Will sync when ready"
}

val result = Synheart.ingestion.flushIfEligible()
if (!result.success) println(result.errorMessage)   // names a closed gate

Drive user-facing copy from cloudSyncStatus or lastIngestSuccessAtMs. uploadQueueLength fluctuates on every flush tick and is a diagnostic, not UI. See Cloud Protocol for wire-level details.

Errors and diagnostics

SynheartCoreError carries a stable machine-readable code. Branch on the code rather than the message.

try {
    Synheart.initialize(context = this, config = config)
    Synheart.startSession()
} catch (e: SynheartCoreError) {
    when (e.code) {
        "ERR_NOT_CONFIGURED" -> println("Missing appId / subjectId")
        "ERR_SESSION_ACTIVE" -> println("A session is already running")
        else -> println("${e.code}: ${e.message}")
    }
} catch (e: IllegalStateException) {
    println("Not startable: ${e.message}")
}

Common codes: ERR_NOT_CONFIGURED, ERR_INVALID_MODE, ERR_RESEARCH_NOT_ALLOWED, ERR_SESSION_ACTIVE, ERR_NO_ACTIVE_SESSION, ERR_STORAGE_DISABLED, ERR_SYNC_DISABLED. Cloud operations throw a CloudConnectorException subtype (ConsentRequiredError, TokenExpiredError, RateLimitExceededError, SchemaValidationError, NetworkError, …). Sync calls throw SyncNativeException so the runtime’s reason survives:

try {
    Synheart.syncNow()
} catch (e: SyncNativeException) {
    when {
        e.isUnsupported   -> disableCloudPermanently()  // never possible on this hardware
        e.isMisconfigured -> reportToDeveloper(e)       // a human has to fix setup
        e.retryable       -> scheduleRetry(e.retryAfterMs)
        else -> showError(e.message)
    }
}

Branch on the is* helpers rather than retryable alone — retryable says whether to try again, not whether it can ever work. Check runtime health with Synheart.runtimeDiagnostics(), the native runtime’s version with Synheart.runtimeVersion, and this SDK’s own version with SYNHEART_CORE_VERSION. To see why an integration stalled, route the runtime’s own logs somewhere:

SynheartConfig(
    appId = "com.example.app",
    subjectId = "user-123",
    runtimeLogEnvFilter = "info",
)

Without a filter the runtime logs nowhere, and the silence reads as “nothing happened” rather than “you never asked to be told”.

Upgrading to 0.2.0

Change	What to do
Breaking: module activation now follows the config.	Declare `wearConfig`, `phoneConfig`, or `behaviorConfig` for the collectors you want. A host that declares none collects nothing.
Breaking: no built-in API host.	Set `ApiEndpoints.baseUrlOverride`, `synheart.baseUrl`, or `SYNHEART_BASE_URL` on any cloud build.
Synthetic biosignals are off by default.	Opt in with `allowSyntheticBiosignals = true` for development only — the samples enter the runtime’s baselines exactly as real readings would.
Behavior events reached no collector before 0.2.0.	Forward touches with `recordTouchEvent`; the digital axes now resolve without a wearable.

0.2.0 also adds watch sessions, a real Health Connect and BLE wear source, requestWearPermissions(), HSIState.modalities / tiers, and runtimeLogEnvFilter. See the changelog for the full list, including the four device-verified bug fixes.

Advanced APIs

The library also provides local session storage and retention, cross-device sync and baseline transfer, sleep/recovery/readiness scoring, Health Connect backfill, watch-to-phone EdgeIngest, lab protocols and research enrolment, secondary SynheartInstance runtime handles, and Syni integration. Start with the lifecycle above. Integrate advanced APIs only when your product needs them:

Architecture

Runtime, modules, and data flow

Consent System

Consent channels and JWT lifecycle

Scoring Models

Sleep, recovery, and readiness

Edge

Watch-to-phone artifacts and ingest

Testing

./gradlew :synheart-core:test

The SDK repository includes a runnable example app and a Wear OS companion. It runs without cloud credentials, so it needs no platform account — only the installed native runtime:

Android example application

Initialization, consent, sessions, HSI, watch integration, and runtime diagnostics

​What this SDK does

​Requirements

​Installation

​1. Add the dependency

​2. Install the native runtime

​3. Declare permissions

​4. Verify before writing integration code

​Start here

​Initialization

​Modes

​Running without cloud credentials

​Consent

​Feature activation and sessions

​Reading HSI

​Typed state

​Canonical JSON

​Raw source streams

​Behavior capture

​Wearable permissions

​Watch sessions

​Production device authentication

​Endpoints

​Cloud upload

​Errors and diagnostics

​Upgrading to 0.2.0

​Advanced APIs

Architecture

Consent System

Scoring Models

Edge

​Testing

Android example application

​Resources

What this SDK does

Requirements

Installation

1. Add the dependency

2. Install the native runtime

3. Declare permissions

4. Verify before writing integration code

Start here

Initialization

Modes

Running without cloud credentials

Consent

Feature activation and sessions

Reading HSI

Typed state

Canonical JSON

Raw source streams

Behavior capture

Wearable permissions

Watch sessions

Production device authentication

Endpoints

Cloud upload

Errors and diagnostics

Upgrading to 0.2.0

Advanced APIs

Testing

Resources