Synheart Behavior Overview - Synheart Documentation

What is Synheart Behavior?

Synheart Behavior is a multi-platform SDK that collects behavioral events from digital interactions (scroll, tap, swipe, typing timing, app switches, notifications, calls) directly on device and streams them to your app. Events are content-free: timing and physical metadata only. The SDKs are event producers. They report events and raw per-session counts; focus, distraction and typing scores are computed downstream by the Synheart runtime when behavior is fed through Synheart Core.

Key Features

On-Device Collection

Events are captured and summarized locally
No network calls
No raw interaction data leaves the device unless your app sends it

Privacy-First Design

No PII: No names, contacts, or user-identifying data
No content capture: No text, images, or semantic data
No keystroke logging: Typing is captured as timing only, never characters
Event-level metadata only: Timing and physical metrics only

Multi-Platform

Platform	SDK	Installation	Min OS	Version	Status
Flutter	`synheart_behavior`	`flutter pub add synheart_behavior`	iOS 12+ / Android API 21+	0.4.1	✅ Ready
Kotlin/Android	`ai.synheart:synheart-behavior`	Gradle: `implementation 'ai.synheart:synheart-behavior:0.6.0'`	Android API 21+	0.6.0	✅ Ready
Swift/iOS	SynheartBehavior	Swift Package: `.package(url: "https://github.com/synheart-ai/synheart-behavior-swift.git", from: "0.5.0")`	iOS 13.0+ / macOS 10.15+	0.5.0	✅ Ready

Architecture

User Interactions
   └─(scroll, tap, swipe, typing, notifications, calls)──► Synheart Behavior SDK
            [Event Collectors] → BehaviorEvents + raw session counts
                                        │
                                        ▼
                         Your App  (or Synheart Core for scoring and HSI fusion)

Components:

Event Collectors: Capture scroll, tap, swipe, app_switch, notification, call, typing, and clipboard events.
Session summary: Raw counts per session (events, app switches, notifications, calls) plus device and system context.
Motion: Kotlin runs an on-device motion-state model (LAYING, MOVING, SITTING, STANDING) when enableMotionLite is on. Flutter and Swift instead emit raw 50 Hz accelerometer samples (emitRawMotionSamples) for the runtime to classify.

Use the SDK standalone for raw events, or feed it into Synheart Core to fuse with biosignals into HSI.

Quick Start

import 'package:synheart_behavior/synheart_behavior.dart';

final behavior = await SynheartBehavior.initialize(
  config: const BehaviorConfig(
    enableInputSignals: true,
    enableAttentionSignals: true,
  ),
);

// Wrap app to enable gesture tracking
return behavior.wrapWithGestureDetector(
  MaterialApp(...),
);

// Listen to real-time events
behavior.onEvent.listen((event) {
  print('Event: ${event.eventType} at ${event.timestamp}');
});

// Start and end a session
final session = await behavior.startSession();
// ... user interacts with app ...
final summary = await session.end();
print('Events: ${summary.activitySummary.totalEvents}, '
      'app switches: ${summary.activitySummary.appSwitchCount}');

Full Flutter SDK Guide →

Use Cases

Focus and distraction

Feed behavior into Synheart Core and read the digital axes of each HSI window. The behavior SDK itself no longer returns focus or distraction scores: BehaviorSessionSummary.behavioralMetrics is always null.

Digital wellness analytics

Track raw interaction patterns per session: event counts, app switches, notification and call counts, and device context (brightness, orientation, Do Not Disturb, charging).

Interaction research

Subscribe to the event stream and keep the per-event timing metrics (tap duration, scroll velocity, typing cadence) for your own analysis.

Behavioral metrics

Focus, distraction, task-switching and typing metrics are computed by the Synheart runtime from the event stream. See Metric definitions for what each one means. The BehavioralMetrics and TypingSessionSummary types still exist in the SDKs, but the SDKs leave them null.

Motion state

Platform	What `enableMotionLite` does	Raw samples
Kotlin	Collects accelerometer and gyroscope at 50 Hz and runs the on-device model; the result is `summary.motionState`	—
Flutter	Starts the native motion collector; no on-device classification	`emitRawMotionSamples: true` → `onMotionSample`
Swift	Nothing yet	`emitRawMotionSamples: true` → `setRawMotionSampleHandler`

// Kotlin
val summary = session.end()
summary.motionState?.let {
    println("Motion: ${it.majorState} (confidence ${it.confidence})")
}

API Features

Feature	Flutter	Kotlin	Swift
Real-time event stream	✅	✅	✅
Session summaries (raw counts)	✅	✅	✅
Time-range counts (`calculateMetricsForTimeRange`)	✅	—	—
On-device motion state	—	✅	—
Raw motion samples	✅	—	✅
Notification events	✅	✅	✅
Call events	Android only	✅	✅
Auto-end after 1 min in background	—	✅	—

Available SDKs

Flutter SDK

Cross-platform mobile apps (iOS + Android)

Kotlin/Android SDK

Native Android applications

Swift/iOS SDK

Native iOS applications

Each repo ships a runnable example in its example/ directory: Flutter · Kotlin · Swift.

Stability

Synheart Behavior is pre-1.0. Minor version bumps may include breaking API changes — pin exact versions in production, and read the CHANGELOG before upgrading. The three language SDKs are versioned independently (Flutter 0.4.x, Kotlin 0.6.x, Swift 0.5.x at time of writing); check each before bumping.

Privacy & Security

On-Device Processing: Events are captured and summarized locally
No Data Retention: The SDK keeps no events after a session ends
No Network Calls: No data is sent to external servers
Privacy-First Design: No built-in storage - you control what gets persisted
No Content Capture: No text, images, or semantic data collected
Event-Level Metadata Only: Only timing and physical metrics

Resources

Dart: synheart-behavior-flutter · pub.dev
Kotlin: synheart-behavior-kotlin · Maven Central
Swift: synheart-behavior-swift

Citation

If you use this SDK in your research:

@software{synheart_behavior,
  title = {Synheart Behavior: Multi-platform SDK for on-device behavioral event collection from digital interactions},
  author = {Synheart AI Team},
  year = {2025},
  version = {0.4.1},
  url = {https://github.com/synheart-ai/synheart-behavior-flutter}
}