Skip to main content

​
Overview

The Synheart Core Android/Kotlin SDK provides a unified API for collecting HSI-compatible data, processing human state on-device, and generating focus/emotion signals in native Android applications. Key Features:
  • Native Android support
  • On-device HSI Runtime
  • Kotlin Coroutines and Flow integration
  • Real-time state updates
  • Privacy-first architecture

​
Installation

Add to your build.gradle (app level): 
dependencies {
    implementation("ai.synheart:synheart-core:0.0.4")
}

​
Configuration

​
AndroidManifest.xml

Add required permissions: 
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required permissions -->
    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />

    <!-- Health Connect Permissions (if using Wear module) -->
    <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
    <uses-permission android:name="android.permission.health.READ_HEART_RATE_VARIABILITY"/>

    <application>
        <!-- Your application configuration -->
    </application>
</manifest>

​
Basic Usage

​
Initialize the SDK

import ai.synheart.core.Synheart
import ai.synheart.core.SynheartConfig

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize Synheart Core
        Synheart.initialize(
            context = this,
            userId = "anon_user_123",
            config = SynheartConfig(
                allowUnsignedCapabilities = true  // Use capabilityToken in production
            )
        )
    }
}

​
Subscribe to HSI Updates

import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

lifecycleScope.launch {
    Synheart.onHSIUpdate.collect { hsiJson ->
        Log.d("HSI", "HSI JSON: $hsiJson")
    }
}

​
Activate features

The SynheartFeature enum gates collection by feature. Activation is one of four conditions a feature needs (consent, capability tier, an active session — see Capability System). 
// Available features:
//   SynheartFeature.WEAR          — biosignals from wearables
//   SynheartFeature.BEHAVIOR      — interaction telemetry
//   SynheartFeature.PHONE_CONTEXT — motion / screen / app context
//   SynheartFeature.CLOUD         — HSI upload connector

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

// Stop a feature without uninitializing the SDK.
Synheart.deactivate(SynheartFeature.CLOUD)
State signals (focus, emotion, recovery, etc.) are not separate features — they’re axes inside the HSI JSON emitted by Synheart.onHSIUpdate. Parse the JSON to read them.

​
Complete example

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.lifecycle.lifecycleScope
import ai.synheart.core.Synheart
import ai.synheart.core.SynheartConfig
import ai.synheart.core.config.SynheartFeature
import kotlinx.coroutines.launch

class HumanStateActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        lifecycleScope.launch {
            Synheart.initialize(
                context = applicationContext,
                userId = "user_123",
                config = SynheartConfig(allowUnsignedCapabilities = true),
            )
            Synheart.activate(SynheartFeature.WEAR)
            Synheart.activate(SynheartFeature.BEHAVIOR)
        }
        setContent { HumanStateMonitor() }
    }
}

@Composable
fun HumanStateMonitor() {
    var hsiJson by remember { mutableStateOf<String?>(null) }
    LaunchedEffect(Unit) {
        Synheart.onHSIUpdate.collect { hsiJson = it }
    }
    Scaffold(topBar = { TopAppBar(title = { Text("Human State") }) }) { p ->
        Column(Modifier.padding(p).padding(16.dp)) {
            Text("HSI: ${hsiJson?.take(100) ?: "Waiting…"}")
        }
    }
}

​
HSI snapshot reference

The HSI Runtime emits raw JSON strings via Synheart.onHSIUpdate (Flow<String>). Parse the JSON to extract fields like the affect / engagement / activity / context axes. See the HSI specification for the wire format.

​
Cloud connector

// Enable cloud sync (requires cloudConfig in SynheartConfig and a
// granted cloudUpload consent).
Synheart.activate(SynheartFeature.CLOUD)

// Pause uploads without tearing down the SDK.
Synheart.deactivate(SynheartFeature.CLOUD)

​
Configuration options

val config = SynheartConfig(
    allowUnsignedCapabilities = true,  // use capabilityToken in production

    // Cloud configuration (optional).
    cloudConfig = CloudConfig(
        appId = "your_app_id",
        subjectId = "user_123",
        instanceId = "device_abc",
        baseUrl = "https://api.synheart.ai",
    ),

    // Capability JWT (optional, for extended/research access).
    capabilityToken = null,
)

Synheart.initialize(
    context = context,
    userId = "user_123",
    config = config,
)
Authentication for cloud uploads is hardware-backed device ECDSA (Android Keystore) per RFC-AUTH-MOBILE-0001. The runtime owns request signing via the host’s synheart-auth integration — CloudConfig does not carry shared secrets or HMAC keys. See Synheart Auth overview for the device-identity flow.

​
Diagnostics & upload inspection

Use the diagnostics surface to inspect runtime state and force a flush when consent and network are eligible. 
// Live counters / last-error strings.
val diag = Synheart.runtimeDiagnostics()
Log.d("Synheart", diag.toString())

// Synchronous getters — safe to read from UI code.
val depth = Synheart.uploadQueueLength
val lastMs = Synheart.lastIngestSuccessAtMs

// Manually flush queued snapshots when eligible.
val result = Synheart.ingestion.flushIfEligible()

​
Error Handling

try {
    Synheart.initialize(
        context = context,
        userId = userId,
        config = config
    )
} catch (e: PermissionDeniedException) {
    Log.e("Synheart", "Permission denied: ${e.message}")
} catch (e: InitializationException) {
    Log.e("Synheart", "Initialization failed: ${e.message}")
} catch (e: SynheartException) {
    Log.e("Synheart", "SDK error: ${e.message}")
}

// Coarse status — granted | pending | expired | denied
val status = Synheart.consentStatus()

// Per-type check (wire strings: biosignals, phoneContext, behavior,
// cloudUpload, vendorSync, research)
val canUpload = Synheart.hasConsent("cloudUpload")
val canRead   = Synheart.hasConsent("biosignals")

// Request consent — opens the cloud consent flow when configured.
val token = Synheart.requestConsent()

if (Synheart.hasConsent("cloudUpload")) {
    Synheart.activate(SynheartFeature.CLOUD)
}

// Revoke a single type or everything
Synheart.revokeConsentType("cloudUpload")
Synheart.revokeConsent()
See Consent System for the full consent model.

​
API Reference

​
Synheart

Main SDK object. Methods:
MethodDescriptionReturns
initialize()Initialize the SDKUnit
activate(feature)Activate a feature moduleUnit
deactivate(feature)Deactivate a feature moduleUnit
dispose()Cleanup resourcesUnit
Flows:
FlowTypeDescription
onHSIUpdateFlow<String>Raw HSI 1.3 JSON, emitted per window close

​
Resources