Skip to main content
The behavior SDK has a small, mostly-quiet error surface. Missing permissions show up as missing events and zero counts, not exceptions. Misuse of the API throws.

Surfaces

Thrown errors

Lifecycle details:
  • Starting a session while one is running: Kotlin ends the previous session first. Flutter and Swift start the new one without ending the old.
  • Ending a session twice: the second call fails; the SDKs don’t cache the summary.
  • After dispose(): Flutter calls throw the “not initialized” exception, and sendEvent silently does nothing.

consentBehavior

BehaviorConfig.consentBehavior is carried into payloads, but no SDK reads it to stop collection: events flow with consentBehavior = false. Gate collection in your app (don’t call initialize() or startSession() without consent), or rely on the runtime’s Behavior consent gate described below.

Permission failures

The SDK does not throw when a platform permission is missing. Instead: Hosts query availability via:
  • checkNotificationPermission() / requestNotificationPermission() — all three SDKs (async on Swift).
  • checkCallPermission() / requestCallPermission() — all three SDKs.
  • Kotlin also has checkNotificationListenerEnabled() / checkNotificationListenerConnected().

Native channel errors (Flutter)

If the native plugin isn’t registered (for example a desktop build without the platform layer), method-channel calls fail with MissingPluginException, and SDK calls that wrap them throw Exception('Failed to …'). Verify plugin registration and the platform build steps.

Motion

  • Kotlin: when enableMotionLite = true and the bundled ONNX model fails to load, the failure is logged, motionState stays null for the session, and events continue normally.
  • Flutter: onMotionSample emits only when emitRawMotionSamples: true.
  • Swift: raw samples arrive only when emitRawMotionSamples: true and a handler is set with setRawMotionSampleHandler.

Runtime gate drops

When the host wires the SDK into synheart-core → the Synheart runtime, behavior events pass through the runtime’s consent gate. If Behavior consent is not granted, the runtime drops events at the engine seam silently. The SDK sees no error — events fire on onEvent, but the runtime never persists or aggregates them. This is intentional: SDK-side telemetry remains coherent (UIs still see live events) while the privacy boundary is enforced past the SDK.

Validation invariants

  • BehaviorSessionSummary is returned on session end even when no events flowed.
  • BehaviorEvent.timestamp is an ISO-8601 string.