Skip to main content

​
Overview

The Synheart Behavior Swift/iOS SDK provides real-time behavioral signal inference from digital interactions for native iOS applications. It requires synheart-flux (Rust library) for HSI-compliant metrics.

​
Installation

​
Swift Package Manager

Add to your Package.swift or in Xcode (File → Add Packages…): 
dependencies: [
    .package(url: "https://github.com/synheart-ai/synheart-behavior-ios.git", from: "0.2.0")
]
Or in Xcode: add package URL and select version 0.2.0.

​
synheart-flux (required)

The SDK requires synheart-flux for all behavioral and typing metrics:
  1. Download SynheartFlux.xcframework from synheart-flux releases.
  2. Add it to your app target (Frameworks, Libraries, and Embedded Content).
  3. For clipboard_activity_rate and correction_rate in the typing summary, use synheart-flux 0.3.0 or later.
See the SDK repo’s SYNHEART_FLUX_INTEGRATION.md for details.

​
Requirements

  • iOS 12.0+
  • Swift 5.0+
  • Xcode 12.0+

​
Quick Start

​
Basic Usage

import SynheartBehavior

let config = BehaviorConfig(
    enableInputSignals: true,
    enableAttentionSignals: true
)

let behavior = SynheartBehavior(config: config)
try behavior.initialize()

guard behavior.isFluxAvailable else {
    fatalError("synheart-flux is required")
}

// Start a session
let sessionId = try behavior.startSession()

// Optional: handle events
behavior.setEventHandler { event in
    print("Event: \(event.type) at \(event.timestamp)")
}

// ... user interacts with app ...

// End session and get HSI metrics
let (hsiPayload, rawHsiJson) = try behavior.endSessionWithHsi(sessionId: sessionId)

​
Session and HSI Output

let sessionId = try behavior.startSession()

// ... user interacts ...

let (hsiPayload, rawHsiJson) = try behavior.endSessionWithHsi(sessionId: sessionId)

if let window = hsiPayload.behaviorWindows.first {
    print("Focus hint: \(window.behavior.focusHint)")
    print("Distraction score: \(window.behavior.distractionScore)")
    print("Task switch rate: \(window.behavior.taskSwitchRate)")
}

​
Typing: clipboard and correction rates

When using synheart-flux 0.3.0+, the typing session summary includes:
  • clipboard_activity_rate: (copy + paste + cut) / (typing taps + clipboard actions)
  • correction_rate: (backspace + delete) / (typing taps + backspace + delete)
The SDK infers backspace from text length decrease; cut is not counted as backspace. For copy/paste/cut, call:
  • behavior.recordCopy()
  • behavior.recordPaste()
  • behavior.recordCut()
when the user performs those actions (e.g. from a custom UITextField/UITextView that overrides copy(_:), paste(_:), cut(_:)). The Example app uses BehaviorTrackingTextField for this.

​
Event behavior

  • Taps and long press: Not counted when a text field or text view is first responder (keyboard open), so typing is not double-counted as tap events.
  • Typing events: Include full metrics (speed, cadence, burstiness, cadence variability, gap ratio, activity ratio, backspace/copy/paste/cut counts).

​
API summary

Method / propertyDescription
initialize()Initialize the SDK
startSession(sessionId?)Start a session; returns session ID
endSession(sessionId)End session and get basic summary
endSessionWithHsi(sessionId)End session and get HSI payload + raw JSON (requires Flux)
setEventHandler(_:)Set callback for real-time events
recordCopy() / recordPaste() / recordCut()Report clipboard actions for typing summary
isFluxAvailableWhether synheart-flux is loaded
getCurrentStats()Current rolling statistics
getSessionEvents()Events for the current session

​
Resources

Author: Synheart AI Team