> ## 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.

# Synheart Behavior — Swift / iOS SDK

> On-device behavioral signal capture for iOS applications

## Overview

The Synheart Behavior Swift/iOS SDK captures digital interaction events on-device — the eight `BehaviorEventType` cases are `scroll`, `tap`, `swipe`, `appSwitch`, `notification`, `call`, `typing`, and `clipboard` — and aggregates them into per-session summaries. Behavior is content-free — no text, no screen content, no PII.

The SDK is an **input layer**: it produces events and session summaries. Higher-level human-state inference (focus, distraction, HSI fusion) is performed downstream by [Synheart Core](/synheart-core/overview) when behavior is fed into it.

## Installation

### Swift Package Manager

Add to your `Package.swift` or in Xcode (File → Add Packages...):

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/synheart-ai/synheart-behavior-swift.git", from: "0.2.0")
]
```

### Requirements

* iOS 12.0+
* Swift 5.0+
* Xcode 12.0+

## Quick Start

```swift theme={null}
import SynheartBehavior

let config = BehaviorConfig(
    enableInputSignals: true,
    enableAttentionSignals: true,
    enableMotionLite: false,
    consentBehavior: true
)

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

// Real-time event stream
behavior.setEventHandler { event in
    print("Event: \(event.type) at \(event.timestamp)")
}

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

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

let summary = try behavior.endSession(sessionId: sessionId)
print("Total events: \(summary.totalEvents)")
print("Typing speed: \(summary.typingSessionSummary?.typingSpeed ?? 0)")
```

## Typing: clipboard and correction rates

The typing session summary includes `clipboardActivityRate` and `correctionRate`, derived from backspace/copy/paste/cut event counts emitted by the SDK.

* **Backspace/correction**: Inferred from text length decrease. Cut is not counted as backspace.
* **Copy/paste/cut**: The SDK does not observe the system clipboard. 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 taps.
* **Typing events**: Include speed, cadence, burstiness, cadence variability, gap ratio, activity ratio, and backspace/copy/paste/cut counts.

## API summary

| Method / property                                | Description                                     |
| ------------------------------------------------ | ----------------------------------------------- |
| `initialize()`                                   | Initialize the SDK                              |
| `startSession(sessionId?)`                       | Start a session; returns session ID             |
| `endSession(sessionId)`                          | End session and return `BehaviorSessionSummary` |
| `setEventHandler(_:)`                            | Set callback for real-time events               |
| `recordCopy()` / `recordPaste()` / `recordCut()` | Report clipboard actions for the typing summary |
| `getCurrentStats()`                              | Current rolling statistics                      |
| `getSessionEvents()`                             | Events for the current session                  |

## Resources

* **Repository**: [synheart-behavior-swift](https://github.com/synheart-ai/synheart-behavior-swift)