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:1.1.0")
}

​
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")
    }
}

​
Enable Interpretation Modules

// Enable Focus tracking
lifecycleScope.launch {
    Synheart.activate(SynheartFeature.FOCUS)

    Synheart.onFocusUpdate.collect { focus ->
        Log.d("Focus", "Score: ${focus.score}")
        Log.d("Focus", "Cognitive Load: ${focus.cognitiveLoad}")
    }
}

// Enable Emotion tracking
lifecycleScope.launch {
    Synheart.activate(SynheartFeature.EMOTION)

    Synheart.onEmotionUpdate.collect { emotion ->
        Log.d("Emotion", "Stress: ${emotion.stress}")
        Log.d("Emotion", "Valence: ${emotion.valence}")
    }
}

​
Enable Cloud Sync

lifecycleScope.launch {
    Synheart.activate(SynheartFeature.CLOUD)
}

​
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.model.*
import kotlinx.coroutines.launch

class HumanStateActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Initialize SDK
        lifecycleScope.launch {
            initializeSynheart()
        }

        setContent {
            HumanStateMonitor()
        }
    }

    private suspend fun initializeSynheart() {
        Synheart.initialize(
            context = applicationContext,
            userId = "user_123",
            config = SynheartConfig(
                allowUnsignedCapabilities = true  // Use capabilityToken in production
            )
        )

        Synheart.activate(SynheartFeature.FOCUS)
        Synheart.activate(SynheartFeature.EMOTION)
    }
}

@Composable
fun HumanStateMonitor() {
    var hsiJson by remember { mutableStateOf<String?>(null) }
    var focusState by remember { mutableStateOf<FocusState?>(null) }
    var emotionState by remember { mutableStateOf<EmotionState?>(null) }

    LaunchedEffect(Unit) {
        launch {
            Synheart.onHSIUpdate.collect { hsiJson = it }
        }
        launch {
            Synheart.onFocusUpdate.collect { focusState = it }
        }
        launch {
            Synheart.onEmotionUpdate.collect { emotionState = it }
        }
    }

    Scaffold(
        topBar = {
            TopAppBar(title = { Text("Human State Monitor") })
        }
    ) { padding ->
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(padding)
                .padding(16.dp),
            verticalArrangement = Arrangement.spacedBy(16.dp)
        ) {
            // HSI Snapshot Card
            Card(modifier = Modifier.fillMaxWidth()) {
                Column(modifier = Modifier.padding(16.dp)) {
                    Text("HSI Snapshot", style = MaterialTheme.typography.titleLarge)
                    Spacer(modifier = Modifier.height(8.dp))
                    hsiJson?.let { json ->
                        Text("HSI: ${json.take(100)}")
                    } ?: Text("Waiting for data...")
                }
            }

            // Focus Card
            Card(modifier = Modifier.fillMaxWidth()) {
                Column(modifier = Modifier.padding(16.dp)) {
                    Text("Focus", style = MaterialTheme.typography.titleLarge)
                    Spacer(modifier = Modifier.height(8.dp))
                    focusState?.let { focus ->
                        Text("Score: ${"%.2f".format(focus.score)}")
                        Text("Cognitive Load: ${"%.2f".format(focus.cognitiveLoad)}")
                        LinearProgressIndicator(
                            progress = focus.score,
                            modifier = Modifier.fillMaxWidth()
                        )
                    } ?: Text("Waiting for data...")
                }
            }

            // Emotion Card
            Card(modifier = Modifier.fillMaxWidth()) {
                Column(modifier = Modifier.padding(16.dp)) {
                    Text("Emotion", style = MaterialTheme.typography.titleLarge)
                    Spacer(modifier = Modifier.height(8.dp))
                    emotionState?.let { emotion ->
                        Text("Stress: ${"%.2f".format(emotion.stress)}")
                        Text("Calm: ${"%.2f".format(emotion.calm)}")
                        Text("Valence: ${"%.2f".format(emotion.valence)}")
                    } ?: Text("Waiting for data...")
                }
            }
        }
    }
}

​
HSI Snapshot Reference

The HSISnapshot is the immutable export format produced by the HSI Runtime: 
data class HSISnapshot(
    val hsiVersion: String,   // "1.0"
    val timestampMs: Long,
    val payload: JsonObject    // HSI 1.0 JSON payload
)
The HSI Runtime now emits raw JSON strings via onHSIUpdate (Flow<String>). Parse the JSON to extract fields.

​
EmotionState Reference

data class EmotionState(
    val stress: Float,       // 0.0-1.0
    val calm: Float,         // 0.0-1.0
    val engagement: Float,   // 0.0-1.0
    val activation: Float,   // 0.0-1.0
    val valence: Float       // -1.0 to 1.0
)

​
FocusState Reference

data class FocusState(
    val score: Float,          // 0.0-1.0
    val cognitiveLoad: Float,  // 0.0-1.0
    val clarity: Float,        // 0.0-1.0
    val distraction: Float     // 0.0-1.0
)

​
Focus Module

// Enable focus tracking
Synheart.activate(SynheartFeature.FOCUS)

lifecycleScope.launch {
    Synheart.onFocusUpdate.collect { focus ->
        Log.d("Focus", "Score: ${focus.score}")
        Log.d("Focus", "Cognitive Load: ${focus.cognitiveLoad}")
        Log.d("Focus", "Clarity: ${focus.clarity}")
        Log.d("Focus", "Distraction: ${focus.distraction}")

        if (focus.score > 0.8) {
            showNotification("You're in the zone!")
        } else if (focus.distraction > 0.7) {
            showNotification("Take a break?")
        }
    }
}

// Disable when done
Synheart.deactivate(SynheartFeature.FOCUS)

​
Emotion Module

// Enable emotion tracking
Synheart.activate(SynheartFeature.EMOTION)

lifecycleScope.launch {
    Synheart.onEmotionUpdate.collect { emotion ->
        if (emotion.stress > 0.7) {
            triggerStressAlert()
        }

        Log.d("Emotion", "Stress: ${emotion.stress}")
        Log.d("Emotion", "Calm: ${emotion.calm}")
        Log.d("Emotion", "Engagement: ${emotion.engagement}")
        Log.d("Emotion", "Activation: ${emotion.activation}")
        Log.d("Emotion", "Valence: ${emotion.valence}")
    }
}

// Disable when done
Synheart.deactivate(SynheartFeature.EMOTION)

​
Cloud Connector

// Enable cloud sync (requires cloudConfig in SynheartConfig)
Synheart.activate(SynheartFeature.CLOUD)

// Disable cloud sync
Synheart.deactivate(SynheartFeature.CLOUD)

​
Configuration Options

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

    // Cloud configuration (optional)
    cloudConfig = CloudConfig(
        tenantId = "your_tenant_id",
        hmacSecret = "your_hmac_secret",
        subjectId = "user_123",
        instanceId = "device_abc",
        baseUrl = "https://api.synheart.com"
    ),

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

Synheart.initialize(
    context = context,
    userId = "user_123",
    config = config
)

​
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}")
}

// Check consent status
val consentStatus = Synheart.getConsentStatus()
Log.d("Consent", "Wear module: ${consentStatus.wear}")
Log.d("Consent", "Cloud sync: ${consentStatus.cloud}")

// Request consent
val granted = Synheart.requestConsent(
    modules = listOf(ConsentModule.WEAR, ConsentModule.CLOUD),
    reason = "We need access to provide personalized insights"
)

if (granted) {
    Synheart.activate(SynheartFeature.CLOUD)
}

// Revoke consent
Synheart.revokeConsent(ConsentModule.CLOUD)

​
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>HSI snapshot updates (raw JSON)
onFocusUpdateFlow<FocusState>Focus state estimates
onEmotionUpdateFlow<EmotionState>Emotion state estimates

​
Resources

Author: Israel Goytom