Overview
The Synheart Behavior Flutter SDK provides real-time behavioral signal inference from digital interactions for cross-platform mobile applications.Installation
Add topubspec.yaml:
Requirements
- Flutter >= 3.10.0
- Dart >= 3.0.0
Quick Start
Basic Usage
Real-Time Event Tracking
Session Management
On-Demand Metrics Calculation
Calculate behavioral metrics for a custom time range within a session:API Reference
SynheartBehavior
Main Methods:
| Method | Description | Returns |
|---|---|---|
initialize({config}) | Initialize SDK | Future<SynheartBehavior> |
wrapWithGestureDetector(widget) | Wrap app to enable gesture tracking | Widget |
startSession({sessionId}) | Start a new session | Future<BehaviorSession> |
calculateMetricsForTimeRange(...) | Calculate metrics for custom time range | Future<Map<String, dynamic>> |
getCurrentStats() | Get current statistics | Future<BehaviorStats> |
onEvent | Stream of behavioral events | Stream<BehaviorEvent> |
dispose() | Clean up resources | void |
calculateMetricsForTimeRange()
Calculate behavioral metrics for a custom time range within a session.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
startTimestampSeconds | int | Yes | Start time as Unix timestamp in seconds |
endTimestampSeconds | int | Yes | End time as Unix timestamp in seconds |
sessionId | String? | No | Session ID (uses current session if not provided) |
Future<Map<String, dynamic>> - Map containing all behavioral metrics for the specified time range
Throws: Exception if time range is out of session bounds or session not found
Example:
| Property | Type | Description |
|---|---|---|
isInitialized | bool | Whether SDK is initialized |
currentSessionId | String? | Current active session ID |
BehaviorConfig
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
enableInputSignals | bool | true | Enable scroll, tap, swipe, typing tracking |
enableAttentionSignals | bool | true | Enable app switching, idle gaps |
enableMotionLite | bool | false | Enable motion state inference |
sessionIdPrefix | String? | null | Prefix for session IDs (null = auto-generated) |
userId | String? | null | Optional user identifier |
deviceId | String? | null | Optional device identifier |
eventBatchSize | int | 10 | Events per batch |
maxIdleGapSeconds | double | 10.0 | Max idle time before task drop |
BehaviorEvent
Properties:
| Property | Type | Description |
|---|---|---|
eventId | String | Unique event identifier |
sessionId | String | Associated session ID |
timestamp | DateTime | Event timestamp |
eventType | BehaviorEventType | Type of event |
metrics | Map<String, dynamic> | Event-specific metrics |
BehaviorEventType.scroll- Scroll interactionsBehaviorEventType.tap- Tap interactionsBehaviorEventType.swipe- Swipe interactionsBehaviorEventType.appSwitch- Foreground / background app-switch events (app_switch)BehaviorEventType.notification- Notification eventsBehaviorEventType.call- Call eventsBehaviorEventType.typing- Typing session events (timing only — never characters)BehaviorEventType.clipboard- Clipboard activity (copy / paste / cut counts only — never content)
BehaviorSession
Methods:
| Method | Description | Returns |
|---|---|---|
end() | End session and get summary | Future<BehaviorSessionSummary> |
| Property | Type | Description |
|---|---|---|
sessionId | String | Session identifier |
BehaviorSessionSummary
Properties:
| Property | Type | Description |
|---|---|---|
sessionId | String | Session identifier |
startAt | String | Session start time (ISO 8601) |
endAt | String | Session end time (ISO 8601) |
durationMs | int (getter) | Session duration in milliseconds |
behavioralMetrics | BehavioralMetrics | Behavioral metrics |
activitySummary | ActivitySummary | Activity summary |
notificationSummary | NotificationSummary | Notification summary |
typingSessionSummary | TypingSessionSummary? | Typing aggregates (when typing was active) |
appId / appName | String | Host app identifiers |
os | Map<String, dynamic> | OS / device platform info |
microSession | MicroSession? | Micro-session metadata |
sessionSpacing | SessionSpacing? | Spacing relative to previous session |
deviceContext | DeviceContext? | Device-state context |
systemState | SystemState? | System-level state at session boundaries |
performanceInfo | PerformanceInfo? | Per-session performance counters |
Motion classification runs in the Synheart Runtime —
consumers subscribe to onMotionSample and forward raw 50 Hz
accelerometer batches to the Synheart Runtime’s motion classifier.
BehavioralMetrics
Properties (12 total):
| Property | Type | Description |
|---|---|---|
interactionIntensity | double | Overall interaction rate (0-1) |
taskSwitchRate | double | App-switching frequency |
taskSwitchCost | int | Task-switch cost in milliseconds |
idleTimeRatio | double | Proportion of session that was idle (0-1) |
activeTimeRatio | double | Proportion of session that was active (0-1) |
notificationLoad | double | Notification pressure |
burstiness | double | Temporal clustering of events |
behavioralDistractionScore | double | Distraction proxy (0-1) |
focusHint | double | Focus quality proxy (0-1) |
fragmentedIdleRatio | double | Fragmented vs. continuous idle |
scrollJitterRate | double | Scroll pattern irregularity |
deepFocusBlocks | List<DeepFocusBlock> | Sustained focus periods |
TypingSessionSummary
The aggregated typing fields live on TypingSessionSummary, accessed
via BehaviorSessionSummary.typingSessionSummary (null when typing
was not active during the session).
| Property | Type | Description |
|---|---|---|
typingSpeed | double | Average typing speed (taps per second) |
typingCadenceStability | double | Consistency of typing rhythm (0-1) |
typingCadenceVariability | double | Variability in timing between taps |
typingActivityRatio | double | Fraction of session with active typing (0-1) |
typingGapRatio | double | Proportion of intervals that are gaps (0-1) |
typingBurstiness | double | Temporal clustering of typing events |
typingInteractionIntensity | double | Overall typing engagement (0-1) |
clipboardActivityRate | double | (copy+paste+cut)/(typing+clipboard) |
correctionRate | double | (backspace+delete)/(typing+backspace+delete) |
Permissions
Notification Permission
Call Permission
Configuration
Update Configuration at Runtime
Resources
- pub.dev: synheart_behavior
- Repository: synheart-behavior-flutter
- Full README: View on GitHub