Skip to main content

Overview

The Synheart Behavior Kotlin/Android SDK collects behavioral events from digital interactions (taps, scrolls, swipes, typing timing, app switches, notifications, calls) in native Android apps and streams them to your app. Since 0.5.0 the SDK is an event producer: it emits events and raw per-session counts, and no longer computes focus, distraction or typing aggregates itself. Those scores are computed downstream by Synheart Core from the event stream. Kotlin is the one platform that still runs the on-device motion-state model.

Installation

Add to your build.gradle: Published to Maven Central as ai.synheart:synheart-behavior:
The old ai.synheart:behavior artifact stopped at 0.3.0.

Requirements

  • Android minSdk 21, compileSdk 34, Java 17
  • Bundles onnxruntime-android 1.18.0 for the motion-state model

Quick Start

Basic Usage

Real-Time Event Tracking

Session Management

startSession() ends any session that is already running before starting the new one.
summary.behavioralMetrics and summary.typingSessionSummary are always null, and notificationIgnoreRate / notificationClusteringIndex are always 0.0: the SDK no longer computes them. Use Synheart Core for focus and distraction scores.

API Reference

SynheartBehavior

Main Methods: Permission helpers are listed under Permissions. Properties:

BehaviorConfig

Parameters:

BehaviorEvent

Properties: Event Types:
  • BehaviorEventType.SCROLL - Scroll interactions
  • BehaviorEventType.TAP - Tap interactions
  • BehaviorEventType.SWIPE - Swipe interactions
  • BehaviorEventType.APP_SWITCH - Foreground / background app-switch events
  • 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

Properties:

BehaviorSessionSummary

Properties:

Permissions

The library’s manifest merges BIND_NOTIFICATION_LISTENER_SERVICE, the SynheartNotificationListenerService declaration and ACCESS_NETWORK_STATE into your app. If you don’t collect notifications, remove the listener:
Call events need READ_PHONE_STATE, which the library does not declare: add it to your own manifest if you want call events.

Notification Permission

Call Permission

Configuration

Update Configuration at Runtime

Note: Configuration can only be updated when no session is active.

View Attachment

To track gestures on specific views, attach the SDK to them:

Automatic Session Ending

Sessions are automatically ended after 1 minute if the app stays in the background. This prevents sessions from running indefinitely when users switch away from your app.

Resources

For comprehensive documentation, see the full README on GitHub.