Documentation Index
Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The Synheart Behavior Flutter SDK provides real-time behavioral signal inference from digital interactions for cross-platform mobile applications.
Installation
Add to pubspec.yaml:
dependencies:
synheart_behavior: ^0.2.1
Install:
Requirements
- Flutter >= 3.10.0
- Dart >= 3.0.0
Quick Start
Basic Usage
import 'package:synheart_behavior/synheart_behavior.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
// Initialize SDK
final behavior = await SynheartBehavior.initialize(
config: const BehaviorConfig(
enableInputSignals: true,
enableAttentionSignals: true,
enableMotionLite: true, // Enable motion state inference (LAYING, MOVING, SITTING, STANDING)
),
);
runApp(MyApp(behavior: behavior));
}
class MyApp extends StatelessWidget {
final SynheartBehavior behavior;
const MyApp({super.key, required this.behavior});
@override
Widget build(BuildContext context) {
return behavior.wrapWithGestureDetector(
MaterialApp(
title: 'My App',
home: HomePage(behavior: behavior),
),
);
}
}
Real-Time Event Tracking
// Listen to real-time events
behavior.onEvent.listen((event) {
print('Event: ${event.eventType} at ${event.timestamp}');
print('Metrics: ${event.metrics}');
// Handle different event types
switch (event.eventType) {
case BehaviorEventType.scroll:
final velocity = event.metrics['velocity'] as double?;
print('Scroll velocity: $velocity px/s');
break;
case BehaviorEventType.tap:
final duration = event.metrics['tap_duration_ms'] as int?;
print('Tap duration: $duration ms');
break;
case BehaviorEventType.swipe:
final direction = event.metrics['direction'] as String?;
print('Swipe direction: $direction');
break;
case BehaviorEventType.typing:
final speed = event.metrics['typing_speed'] as double?;
final tapCount = event.metrics['typing_tap_count'] as int?;
print('Typing speed: $speed, tap count: $tapCount');
break;
default:
break;
}
});
Session Management
// Start a session
final session = await behavior.startSession();
print('Session started: ${session.sessionId}');
// ... user interacts with app ...
// End session and get summary
final summary = await session.end();
print('Session duration: ${summary.durationMs}ms');
print('Total events: ${summary.activitySummary.totalEvents}');
print('Focus hint: ${summary.behavioralMetrics.focusHint}');
print('Distraction score: ${summary.behavioralMetrics.distractionScore}');
On-Demand Metrics Calculation
Calculate behavioral metrics for a custom time range within a session:
// Calculate metrics for a specific time range
final metrics = await behavior.calculateMetricsForTimeRange(
startTimestampSeconds: 1767688063, // Unix timestamp in seconds
endTimestampSeconds: 1767688130, // Unix timestamp in seconds
sessionId: 'SESS-1767688063415', // Optional: uses current session if not provided
);
// Access the calculated metrics
print('Total events: ${metrics['activity_summary']['total_events']}');
print('App switches: ${metrics['activity_summary']['app_switch_count']}');
print('Interaction intensity: ${metrics['behavioral_metrics']['interaction_intensity']}');
print('Distraction score: ${metrics['behavioral_metrics']['behavioral_distraction_score']}');
print('Focus hint: ${metrics['behavioral_metrics']['focus_hint']}');
// Motion state (if motion data is available)
if (metrics['motion_state'] != null) {
print('Motion state: ${metrics['motion_state']['major_state']}');
print('Confidence: ${metrics['motion_state']['confidence']}');
}
// Device context
print('Screen brightness: ${metrics['device_context']['avg_screen_brightness']}');
print('Orientation: ${metrics['device_context']['start_orientation']}');
// System state
print('Internet: ${metrics['system_state']['internet_state']}');
print('Do not disturb: ${metrics['system_state']['do_not_disturb']}');
Note: The time range must be within the session’s start and end times. The SDK automatically validates this and will throw an error if the range is out of bounds.
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) |
Returns: 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:
final metrics = await behavior.calculateMetricsForTimeRange(
startTimestampSeconds: DateTime.now().subtract(Duration(minutes: 5)).millisecondsSinceEpoch ~/ 1000,
endTimestampSeconds: DateTime.now().millisecondsSinceEpoch ~/ 1000,
);
// Access metrics
final totalEvents = metrics['activity_summary']['total_events'] as int;
final intensity = metrics['behavioral_metrics']['interaction_intensity'] as double;
Properties:
| 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 |
Event Types:
BehaviorEventType.scroll - Scroll interactions
BehaviorEventType.tap - Tap interactions
BehaviorEventType.swipe - Swipe interactions
BehaviorEventType.appSwitch - Foreground / background app-switch events (app_switch)
BehaviorEventType.notification - Notification events
BehaviorEventType.call - Call events
BehaviorEventType.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> |
Properties:
| 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
// Check if permission is granted
final hasPermission = await behavior.checkNotificationPermission();
if (!hasPermission) {
// Request permission
final granted = await behavior.requestNotificationPermission();
if (granted) {
print('Notification permission granted');
}
}
Call Permission
// Check if permission is granted
final hasPermission = await behavior.checkCallPermission();
if (!hasPermission) {
// Request permission
await behavior.requestCallPermission();
}
Configuration
Update Configuration at Runtime
await behavior.updateConfig(const BehaviorConfig(
enableInputSignals: true,
enableAttentionSignals: true,
enableMotionLite: true,
));
Resources
For comprehensive documentation, see the full README on GitHub.