Synheart Core - Flutter SDK - Synheart Documentation

What this SDK does

Synheart Core connects a Flutter app to the native Synheart Runtime. It:

collects user-consented wearable, phone, and behavior signals;
sends those signals to the on-device runtime;
exposes Human State Interface (HSI) 1.3 output as Dart streams;
optionally stores, synchronizes, and uploads derived state.

The Flutter package coordinates platform integrations. Human-state computation, storage, device authentication, and sync run in the separately installed native runtime.

HSI is the public output. Most applications should use Synheart.onStateUpdate for typed values or Synheart.onHSIUpdate for the canonical JSON. Internal HSV data does not cross the public SDK boundary.

Requirements

Dart >=3.8.0 <4.0.0
Flutter >=3.32.0
iOS 16 or later
Android API 28 or later
A Synheart Runtime binary installed in the host application

synheart_core itself supports iOS 15 and Android API 24, but it depends on synheart_wear, which needs iOS 16 and API 28. Individual wearable providers can impose additional OS, hardware, or licensing requirements.

Installation

1. Add the Flutter package

flutter pub add synheart_core

Or add the current release to pubspec.yaml:

dependencies:
  synheart_core: ^0.24.0

2. Install the native runtimes

The package alone loads no runtime and produces no HSI. Native artifacts are provisioned by the Synheart CLI, not by pub. Install and authenticate the CLI once:

curl -fsSL https://synheart.sh/install | bash
synheart login

From your Flutter application root:

synheart install runtime --version 0.46.0
synheart install syni

synheart_core 0.23 is verified against runtime 0.46.0 and requires C ABI 4.2 (runtime 0.45.0 or later); older runtimes are refused at initialization. ABI 4.2 changed the daily score inputs, and neither shape parses on the other runtime. synheart doctor checks the installed runtime against the package.

synheart install syni is not optional on iOS. synheart_core depends on the syni package, whose iOS pod links its own vendored framework and fails pod install when it is absent — even if your application never uses Syni.

Commit the generated synheart.lock, which pins each artifact by SHA-256. Other developers and CI can restore the pinned artifacts with:

synheart sync

The CLI installs runtime artifacts under:

iOS: synheart/vendor/runtime/ios/SynheartCoreRuntime.xcframework/
iOS: synheart/vendor/syni-runtime/SyniRuntime.xcframework/
Android: synheart/vendor/runtime/android/jniLibs/<abi>/

3. Configure the platforms

iOS

Set SYNHEART_APP_ROOT near the top of your application’s ios/Podfile:

ENV['SYNHEART_APP_ROOT'] = File.expand_path('..', __dir__)

Treat this as required rather than as a monorepo workaround. The Synheart podspecs symlink their vendored framework from <app>/synheart/vendor/ during pod install. Without it they walk up from the pod’s own source directory, which either fails to find an application root (pods resolved from pub-cache) or reaches a different project that happens to have a synheart/vendor/ directory — linking a runtime your synheart.lock does not pin. Merge these settings into the rest of the Podfile:

platform :ios, '16.0'

target 'Runner' do
  # ONNX Runtime ships as a static binary, so pods must link statically.
  use_frameworks! :linkage => :static

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))

  # CocoaPods trunk serves SynheartAuth 0.1.0; synheart_auth needs 0.1.3.
  pod 'SynheartAuth',
    :git => 'https://github.com/synheart-ai/synheart-auth-swift.git',
    :tag => 'v0.1.3'
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      # Some plugin pods still declare iOS 9–14, below Xcode's minimum.
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '16.0'
      # The runtime's simulator slice is arm64 only.
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'x86_64'
    end
  end
end

Without static linkage, pod install stops with “transitive dependencies that include statically linked binaries: onnxruntime.xcframework”. Without the simulator setting, flutter build ios --simulator fails with Framework 'SynheartCoreRuntime' not found. Running on an Apple silicon simulator with flutter run is not affected. Enable the HealthKit capability when using health data. Add a usage description to ios/Runner/Info.plist:

<key>NSHealthShareUsageDescription</key>
<string>This app reads health data to calculate consented wellbeing insights.</string>

Use permission copy that accurately describes your application. synheart_core 0.23 and later ask Apple Health and Health Connect for read access only, so NSHealthUpdateUsageDescription and the Health Connect WRITE_* permissions are needed only if your app writes health data itself.

Android

Declare only the permissions required by the sources you enable:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

<!-- Health Connect examples -->
<uses-permission android:name="android.permission.health.READ_HEART_RATE" />
<uses-permission android:name="android.permission.health.READ_HEART_RATE_VARIABILITY" />
<uses-permission android:name="android.permission.health.READ_STEPS" />

synheart_behavior 0.4.1 (required by synheart_core) merges its notification listener service and the BIND_NOTIFICATION_LISTENER_SERVICE and READ_PHONE_STATE permissions into your manifest automatically, so you no longer declare them. If your app does not collect notification or call interruptions, remove them:

<manifest xmlns:tools="http://schemas.android.com/tools">
  <uses-permission android:name="android.permission.BIND_NOTIFICATION_LISTENER_SERVICE" tools:node="remove" />
  <uses-permission android:name="android.permission.READ_PHONE_STATE" tools:node="remove" />
  <application>
    <service android:name="ai.synheart.behavior.SynheartNotificationListenerService" tools:node="remove" />
  </application>
</manifest>

Keep app data out of Android backups: the runtime’s secure store is sealed with a device-bound key that a restored copy cannot use. Set android:allowBackup="false" and android:dataExtractionRules on the <application>. On iOS the SDK excludes its data directories from backup itself. Health Connect requires package queries, a permission-rationale intent, and a privacy-policy activity alias. Copy the applicable declarations from the Flutter example manifest. On Android 14 and later, use FlutterFragmentActivity:

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity : FlutterFragmentActivity()

Build your application module against compileSdk 36. Before 0.24.0 the synheart_wear plugin compiled against 34 and the build failed at :synheart_wear:checkDebugAarMetadata unless a subprojects block raised it; with 0.24.0 (synheart_wear 0.7.0) that block is no longer needed.

Start here

The minimum integration has five steps:

Initialize the SDK.
Ask the user for consent.
Subscribe to HSI output.
Start a collection session.
Stop the session and release resources.

The following example uses unsigned capabilities for local development:

import 'dart:async';
import 'package:synheart_core/synheart_core.dart';

late final StreamSubscription<HSIState> hsiSubscription;

Future<void> startSynheart() async {
  await Synheart.initialize(
    config: SynheartConfig(
      appId: 'com.example.my_app',
      subjectId: 'user-123',
      appVersion: '1.0.0',
      allowUnsignedCapabilities: true, // Development only.
      wearConfig: const WearConfig(),
      behaviorConfig: const BehaviorConfig(),
    ),
  );

  await Synheart.grantConsent(
    biosignals: true,
    behavior: true,
    phoneContext: false,
    cloudUpload: false,
  );

  hsiSubscription = Synheart.onStateUpdate.listen((state) {
    print('Focus: ${state.hsi.focus?.value}');
    print('Arousal: ${state.hsi.arousal?.value}');
  });

  await Synheart.startSession();
}

Future<void> stopSynheart() async {
  await Synheart.stopSession();
  await hsiSubscription.cancel();
  await Synheart.dispose();
}

allowUnsignedCapabilities: true bypasses production capability verification. Never enable it in a release build.

Initialization

SynheartConfig.validate() requires:

a non-empty appId;
a non-empty subjectId;
a subjectId that does not contain |;
PrivacyConfig(allowResearch: true) when using research mode.

await Synheart.initialize(
  config: SynheartConfig(
    appId: 'com.example.my_app',
    subjectId: 'pseudonymous-user-id',
    mode: SynheartMode.personal,
    appName: 'My App',
    appVersion: '2.1.0',
    category: 'Wellness',
    developer: 'Example Inc.',
    allowUnsignedCapabilities: true, // Development only.
  ),
  autoStart: false,
);

Passing userId: to initialize() does not populate config.subjectId. Set subjectId on the config itself. initialize() throws SynheartRuntimeException (kind: incompatible) when the installed runtime cannot be used with this SDK: a C ABI other than 4.2 or a later 4.x, a runtime older than 0.45.0, or a library that does not report its build info. Its installCommand is the exact command that fixes it. A missing, wrong-architecture, or unloadable runtime does not throw: the SDK starts without HSI and Synheart.runtimeError says why.

try {
  await Synheart.initialize(config: config);
} on SynheartRuntimeException catch (e) {
  print('${e.message}\nFix: ${e.installCommand}');
}
if (Synheart.runtimeError != null) {
  print('Runtime unavailable: ${Synheart.runtimeError!.message}');
}

Initialization is idempotent. Concurrent callers share the in-progress initialization, and calls made after initialization are no-ops. By default, initialization does not collect data. Call startSession() after consent is ready. Use autoStart: true only when consent has already been completed.

When the health permission prompt appears

WearConfig.autoStartPlatformHealth defaults to true: the HealthKit / Health Connect reader starts as soon as biosignals consent is granted, and the system permission prompt can appear at that moment — before your onboarding has explained it, and again on every launch if you re-grant a remembered consent. To ask only when the user chooses, turn it off and start the reader yourself:

wearConfig: const WearConfig(autoStartPlatformHealth: false),

// later, when the user taps "Connect Health":
await Synheart.startWearCollection();

Turn it off too when your app pushes heart rate itself (Synheart.pushWearHr, from a watch relay or BLE strap) and uses platform health only when the user picks it.

Modes

Mode	Persistence
`SynheartMode.personal`	HSI, session summaries, and baselines
`SynheartMode.insight`	Personal-mode data plus application metrics
`SynheartMode.research`	Can include raw research data; requires explicit privacy configuration and consent. Forwards raw phone motion to the runtime by default (`BehaviorConfig.emitRawMotionSamples`).

When the signed-in identity changes, keep the runtime identity aligned without reinitializing:

final changed = await Synheart.rebindSubjectId('new-subject-id');

Running without cloud credentials

The SDK is usable with no platform account. Omit CloudConfig and DeviceAuthConfig, and everything on-device works: collection, HSI computation, consent, local storage, and baselines. Nothing leaves the device and no attestation is attempted. The runtime consent-form flow needs a ConsentConfig to stamp submissions:

await Synheart.initialize(
  config: SynheartConfig(
    appId: 'com.example.my_app',
    subjectId: 'usr_stable_identifier',
    allowUnsignedCapabilities: true, // Development only.
    wearConfig: const WearConfig(),
    consentConfig: ConsentConfig(
      deviceId: 'dev_stable_identifier',
      platform: 'flutter',
      userId: 'usr_stable_identifier',
    ),
  ),
);

HSI upload, cross-device sync, research-study enrolment, and server-issued capability tokens are unavailable in this configuration. Consent still persists locally; the runtime is offline-first and reconciles with the cloud profile only when cloud upload is enabled. Consent and capability are different:

Capability says what the application is authorized to use.
Consent says what the user allows.

Standard collection features are operational only when activation, consent, capability, and an active session all permit them. Syni also has its own model installation and execution lifecycle; see Syni for Flutter. The seven consent channels are:

biosignals
phoneContext
behavior
cloudUpload
vendorSync
research
syni

Each category is made of finer channels, such as phone_context.device_motion and behavior.app_context. By default a granted category turns on all of its channels. Set SynheartConfig(strictChannelConsent: true) to enforce consent per channel instead: the runtime then accepts a sample only when its own channel is granted (and, when cloud consent is configured, present in the verified consent token), and the SDK checks the same channel before starting a sensor. Available since synheart_core 0.18.0. When a newer version of your app’s published HSM Schema declares an input the person was never asked about, the runtime keeps it off until they consent. Synheart.schemaNeedsConsent() is true while that is the case, and hsmSchemaConsent() returns the schema version and the new channels. Show the consent form again when it is true. A channel the person declined is not asked about again. Available since synheart_core 0.21.0 (runtime 0.43.0 or later). HSI windows reach onHSIUpdate, onStateUpdate and getSessionHsiWindows() when any collection category (biosignals, behavior, phoneContext) or research is granted, so an app that collects only behavior still receives its digital axes. With none of them granted, windows are dropped. Before 0.23.0 a window needed biosignals or research.

await Synheart.grantConsent(
  biosignals: true,
  phoneContext: true,
  behavior: true,
  cloudUpload: false,
  vendorSync: false,
  research: false,
  syni: false,
);

final channels = Synheart.getConsentStatusMap();
print(channels['biosignals']);

Observe consent changes:

final consentSubscription = Synheart.consentChanges.listen((snapshot) {
  print('Cloud upload allowed: ${snapshot.cloudUpload}');
});

Revoke one channel or all consent:

await Synheart.revokeConsentType('behavior');
await Synheart.revokeConsent();

hasConsent() reports whether a channel is currently enforceable, not what the user chose. Once cloud is configured, the runtime denies every channel until a consent token is issued. For hosted consent profiles and JWT lifecycle, see Consent System.

Feature activation and sessions

Module config enables the corresponding module. Features may also be activated explicitly:

Synheart.activate(SynheartFeature.wear);
Synheart.activate(SynheartFeature.behavior);

print(Synheart.isActivated(SynheartFeature.wear));
print(Synheart.isFeatureOperational(SynheartFeature.wear));

Available features are:

Feature	Purpose	Consent
`wear`	Wearable biosignals	`biosignals`
`behavior`	Interaction timing and patterns	`behavior`
`phoneContext`	Motion, screen, and app context	`phoneContext`
`cloud`	HSI cloud upload	`cloudUpload`
`synsync`	Cross-device sync	`cloudUpload`
`syni`	Adaptive AI integration	`syni`

Start and stop the full collection lifecycle:

final session = await Synheart.startSession(durationSec: 30 * 60);
print(session?.sessionId);

// Later:
await Synheart.stopSession();

startSession() requires both halves of a pair: a collection feature enabled in SynheartConfig (wearConfig / behaviorConfig / phoneConfig) and its matching consent granted (biosignals / behavior / phoneContext). Neither alone is enough, and cloudUpload, vendorSync, research, and syni never qualify — they govern what happens to data once gathered. A session that could collect nothing throws a StateError instead of starting.

Or control individual collectors:

await Synheart.startWearCollection(
  interval: const Duration(seconds: 1),
);
await Synheart.startBehaviorCollection();
await Synheart.startPhoneCollection();

await Synheart.stopPhoneCollection();
await Synheart.stopBehaviorCollection();
await Synheart.stopWearCollection();

Module-level methods still enforce consent and capability gates.

Reading HSI

Typed state

Most Flutter applications should use:

final subscription = Synheart.onStateUpdate.listen((state) {
  final focus = state.hsi.focus;
  final stress = state.hsi.stress;

  if (focus != null) {
    print('Focus ${focus.value}, confidence ${focus.confidence}');
  }
  if (stress != null) {
    print('Stress ${stress.value}, confidence ${stress.confidence}');
  }
});

The typed state contains:

class HSIState {
  final String subjectId;
  final int timestampMs;
  final HSIAxes hsi;
  final Modalities modalities;
  final Tiers tiers;
  final String rawJson;
  final String? parseError;
}

class HSIAxes {
  // Physiological and fused axes.
  final HSIAxisValue? focus;
  final HSIAxisValue? arousal;
  final HSIAxisValue? capacity;
  final HSIAxisValue? sleep;
  final HSIAxisValue? stress;

  // Digital axes, derived from interaction rather than physiology.
  final HSIAxisValue? focusQuality;
  final HSIAxisValue? interruptionPressure;
  final HSIAxisValue? interactionMode;
}

Axis values can be null when there is not enough input or when an older payload does not contain that reading. Missing means unknown; it does not mean zero. The digital axes come from interaction, so they resolve on hardware with no biosignal source. Use HSIAxes.hasDigital to check whether the window carried any of them. onStateUpdate parses each HSI window once and shares the result across subscribers. Synheart.currentHSIState reuses the same parse, so it is cheap to read repeatedly.

Canonical JSON

Use the raw stream when forwarding or validating the exact HSI 1.3 envelope:

final subscription = Synheart.onHSIUpdate.listen((hsiJson) {
  sendToYourConsumer(hsiJson);
});

HSIState.rawJson preserves the same JSON. See HSI in Synheart Core for mapping details.

Raw source streams

final wearSubscription = Synheart.wearSampleStream.listen((sample) {
  print('HR: ${sample.hr}');
  print('RR intervals: ${sample.rrIntervals}');
});

final behaviorSubscription =
    Synheart.behaviorEventStream.listen((event) {
  print('${event.type} at ${event.timestamp}');
});

Raw streams are consent-gated. Always cancel subscriptions with their owning widget, provider, or service. Per-session buffers are also available through Synheart.getSessionHsiWindows() and Synheart.getSessionWearSamples(). Both are capped ring buffers — see maxSessionHsiWindows and maxSessionWearSamples.

Personal baselines and daily scores

The runtime keeps the personal baselines on the device and saves and restores them itself. Most apps need no code for this. Push a daily value (for example from a wearable’s nightly summary), then refresh the reference once. Both calls build the engine pipeline when no session is running (since 0.23.0), so a background health pull or vendor sync is stored:

Synheart.srmPushWearableDaily(
  provider: 'garmin_connect',
  metric: DailyMetric.restingHrBpm, // the unit is in the name
  date: wakeDate,                   // the local date the person woke on
  value: 54,
); // 0 = stored
Synheart.srmRefreshWearableReference();

Attach Strain with attachStrainScore() before local midnight, or attachClosedDayStrain() after it. Score a night against the runtime’s baselines. After srmRefreshWearableReference(), read Synheart.dailySleepBaselines() for the Sleep Score and Synheart.dailyBaselineRefs() for Recovery and Readiness:

SleepScoreInput takes tonightMidpointH (the night’s local sleep midpoint, or null without a start and end time) and baselines. Without the baselines the score stays in its cold-start mode.
RecoveryScoreInput.baselines comes from dailyBaselineRefs().
ReadinessScoreInput.baselineMaturity (0..1) is BaselineRefs.maturity, or 0 when dailyBaselineRefs() returns null.

Push heart rate under two names. cardiac.overnight_hr_bpm (DailyMetric.overnightHrBpm) is the mean HR asleep, which the Sleep Score reads. cardiac.resting_hr_bpm is the resting-HR record, which Recovery and Readiness read. A source with one overnight figure fills both. A daytime resting HR on its own fills resting only. Push steps and motion.active_min only for days that are over. Never push cardiac.rest_rmssd_ms; the engine writes it.

Upgrading from 0.19 or earlier? rollDay() and the SRM/longitudinal snapshot calls are gone, and daily values use the new DailyMetric names. The first launch after the upgrade starts the baselines fresh once. From 0.21 or earlier, the score inputs changed with runtime 0.45 (see Upgrading). See the changelog for each change.

Production device authentication

Production applications should configure hardware-backed device identity:

await Synheart.initialize(
  config: SynheartConfig(
    appId: 'app_focus_and_kB8mPx', // platform app_id
    subjectId: 'user-123',
    deviceAuthConfig: const DeviceAuthConfig(
      authBaseUrl: 'https://api.synheart.ai',
      packageName: 'com.example.my_app', // your bundle ID / package name
    ),
    cloudConfig: CloudConfig(
      subjectId: 'user-123',
      instanceId: 'stable-installation-uuid',
      orgId: 'organization-id',
      baseUrl: ApiEndpoints.resolvedCloudBaseUrl,
    ),
  ),
);

The runtime registers a hardware-backed identity and signs supported requests. No shared HMAC secret is required for normal production upload.

DeviceAuthConfig.packageName is the installed bundle id, which Play Integrity and App Attest verify against. It is not SynheartConfig.appId, the platform-issued application identifier. Passing the latter fails attestation.

Registration is triggered by cloud-upload consent, not by initialize(). Configuring DeviceAuthConfig only makes it possible. Device registration is deferred until a cloud-bound action needs it:

final registered = await Synheart.ensureDeviceAuthRegistered();
final status = Synheart.coreDeviceAuthStatus();

Use Synheart.reattestDeviceAuth() as an explicit repair action if the server has lost or revoked an otherwise valid local device identity. It refreshes the attestation without rotating the device identity. (reregisterDeviceAuth() is deprecated and calls it.)

Endpoints

The platform origin is https://api.synheart.ai, but the SDK does not bake it in. SYNHEART_BASE_URL is empty unless you set it, and with nothing configured the native runtime applies its own default. Set it explicitly on any build that talks to the cloud:

flutter run \
  --dart-define=SYNHEART_BASE_URL=https://api.example.com

Optional service-specific overrides:

SYNHEART_AUTH_BASE_URL
SYNHEART_CONSENT_BASE_URL
SYNHEART_INGEST_BASE_URL

Set SYNHEART_BASE_URL rather than relying on a per-service override alone. An override moves one service; the rest keep resolving through SYNHEART_BASE_URL. Overriding auth by itself points device registration at one environment while consent and ingest stay on another, which surfaces as authentication failures with no obvious cause.

The values must be origins. The runtime appends service paths.

Cloud upload

Cloud upload requires:

CloudConfig;
DeviceAuthConfig in production;
cloudUpload consent;
an issued consent token and a registered device.

The runtime uploads on its own. It subscribes to the engine’s HSI broadcast, enqueues each closed window, and POSTs on CloudConfig.uploadInterval. No host code is required to move data. Inspect the queue and user-facing status:

print(Synheart.cloudSyncStatus);
print(Synheart.uploadQueueLength);
print(Synheart.lastIngestSuccessAtMs);
print(Synheart.lastUploadError);

final ready = await Synheart.ensureCloudConsentReady();
final result = await Synheart.ingestion.flushIfEligible();

Use cloudSyncStatus for user interface copy. Queue depth is more useful for diagnostics than for end users. If HSI is produced but nothing uploads, the cause is almost always a closed consent gate — lastUploadError names it. See Cloud Protocol for wire-level details.

Syni chat and sessions

Runtime 0.21.0 and later expose device-signed, non-streaming Syni service calls. Configure SYNHEART_BASE_URL and register the device before calling them. The SDK keeps the active session id after each successful turn, so subsequent calls continue the same conversation until startNewSession().

final syni = Synheart.syni?.service;
if (syni != null && syni.isAvailable) {
  final response = await syni.chat(
    'Help me reflect on today',
    personaId: 'focus.coach.v1',
    includeState: true,
  );

  final sessions = await syni.listSessions(limit: 20);
  final messages = await syni.getSessionMessages(response.sessionId);
  await syni.closeSession(response.sessionId);
}

Chat calls are serialized because sending is non-idempotent and order matters. If a timeout produces a SyniServiceException with deliveryUnknown == true, inspect the session messages before offering a retry; resending immediately could duplicate a turn. On an older native runtime isAvailable is false and the rest of the SDK continues to work. On-device model installation and streaming chat are covered in Syni for Flutter.

Errors and diagnostics

Configuration validation throws SynheartError with a stable code. An incompatible runtime throws SynheartRuntimeException from initialize() (see Initialization). Lifecycle preconditions commonly throw StateError; invalid arguments throw ArgumentError; structured runtime failures throw SynheartNativeException (sync calls throw its subclass SyncNativeException).

try {
  await Synheart.startSession();
} on SynheartError catch (error) {
  print('${error.code}: ${error.message}');
} on SynheartNativeException catch (error) {
  if (error.isUnsupported) {
    // The loaded runtime cannot do this.
  } else if (error.isMisconfigured) {
    // Fix configuration before retrying.
  } else if (error.retryable) {
    // Offer a retry.
  }
} on StateError catch (error) {
  print(error.message);
}

After any native call that failed (returned null, false, or an error code), Synheart.lastNativeError explains it: a SynheartNativeError with code, message, retryable, ownerKind, recoveryKind, recoveryCall, reason, argument, hint, op, and errorId. A call that succeeds clears it. CoreRuntimeBridge.lastCreateError says why the runtime handle could not be created.

await Synheart.grantConsent(cloudUpload: true);
final error = Synheart.lastNativeError;
if (error != null) print('${error.code} (${error.errorId}): ${error.message}');

Check runtime health:

final diagnostics = Synheart.runtimeDiagnostics();
print(diagnostics['isAvailable']);    // bool — native bridge loaded
print(diagnostics['version']);        // String? — native runtime version
print(diagnostics['frameCount']);     // int — HSI frames this session
print(diagnostics['missingSymbols']); // List<String>
print(diagnostics['runtimeError']);   // Map? — {kind, message, cause} when unavailable

missingSymbols lists optional native symbols the loaded runtime does not export. Empty is the healthy state. Anything in it means the vendored runtime predates this SDK release, so the features behind those symbols are disabled and return null, -1, or an empty list rather than throwing. The list fills lazily, so check it after exercising the features you depend on, or pass probeAll: true for a full audit. If isAvailable is false, runtimeError and its install command say why. If symbols are missing, install the runtime the SDK recommends and check it:

synheart install runtime --version 0.46.0
synheart doctor
flutter run

Then inspect the native linker output and verify the runtime exists under synheart/vendor/runtime/.

Threading

Network-touching calls — syncNow(), flushUploads(), fetchCloudHsiWindows(), requestDataDeletion(), device registration, and the consent mutations — run on a background isolate and return a Future. The per-sample push calls (pushWearHr, pushRr, pushAccel, tick, ingestBatch) are synchronous and safe on the UI isolate at sensor rates. Diagnostic getters are cheap synchronous FFI reads, but they are still FFI calls: do not poll them per frame.

Testing

flutter test
flutter analyze --no-fatal-infos

The SDK repository includes a complete example application. It runs without cloud credentials, so it needs no platform account — only the installed native artifacts:

Flutter example application

Initialization, consent, sessions, HSI, watch integration, and runtime diagnostics

Upgrading

Notable changes since 0.10:

Version	Change
0.24.0	Requires `synheart_wear` 0.7.0, which encrypts its session cache with AES-256-GCM and no longer returns empty reads right after `initialize()` on Android. `WearSample.hrvRmssd` no longer carries Apple Health’s SDNN; read the new `WearSample.hrvSdnn`. The `subprojects` block that raised `synheart_wear` to `compileSdk` 36 can be removed.
0.23.0	Requires `synheart_wear` 0.6.2, which asks for health read access only; apps that don’t write health data can drop `NSHealthUpdateUsageDescription` and the Health Connect `WRITE_*` permissions. HSI is delivered when any collection consent (or research) is granted, not only biosignals. `srmPushWearableDaily` and `srmRefreshWearableReference` build the pipeline first, so values pushed with no session running are no longer refused. Resting HR and mean HR asleep are pushed apart. Steps are pushed only for finished days. Garmin `hrv.updated` carries last night’s average.
0.22.1	Install hints recommend runtime 0.46.0, which reports each output no finer than your HSM Schema declares and enforces its `retention`. Runtimes from 0.45.0 still load.
0.22.0	Breaking: requires runtime 0.45.0 or later (C ABI 4.2). `ReadinessScoreInput.baselineDays` is now `baselineMaturity` (`0..1`); `SleepScoreInput` gains `tonightMidpointH` and `baselines`; `RecoveryScoreInput.baselines` comes from `dailyBaselineRefs()`. Added `dailyBaselineRefs()`, `dailySleepBaselines()`, `DailyMetric.overnightHrBpm`, `activeMin` and `restRmssdMs`, and `SynheartConfig.modelBackend`.
0.21.0	Install hints recommend runtime 0.43.0 (C ABI 4.1). Added `schemaNeedsConsent()` and `hsmSchemaConsent()`. Runtime 0.42.x still loads.
0.20.0	Breaking: requires runtime 0.42.0 or later (C ABI 4.0); install hints recommend 0.42.1. `rollDay()` removed (the engine closes each day; `attachClosedDayStrain()` added). SRM and longitudinal snapshot calls replaced by `exportBaselineSnapshot()` / `loadBaselineSnapshot()`; the runtime persists the baselines itself. `srmPushWearableDaily` takes a provider, a `DailyMetric` name and a local date; `srmTriggerWearableRecompute` is `srmRefreshWearableReference`. Added input-capture reporting, `setCallActive`, `pushInputsJson` and the baseline read-outs. `device_class` defaults to `"auto"`. See Personal baselines and daily scores.
0.19.0	Breaking: `getSyncStatus()` removed (use `syncStatus()`); `ReadinessScoreInput` takes `recoveryScore` and `sleepScore`. Added `attachRecoveryScore()`, `attachReadinessScore()` and `syncPairingStatus(token)`.
0.18.1	Install hints recommend runtime 0.41.0.
0.18.0	`SynheartConfig.strictChannelConsent`: the runtime accepts a sample only when its own consent channel is granted. Collectors follow the runtime’s per-channel decision live. `CoreRuntimeBridge.wellnessJson()` deprecated.
0.17.2	iOS: the runtime’s data directories are excluded from iCloud and device backup.
0.17.1	Requires `synheart_auth` ^0.1.12, which recovers an Android secure store restored from a backup.
0.17.0	Breaking (behavior): `initialize()` throws `SynheartRuntimeException` for an incompatible runtime. Added `Synheart.runtimeError`, `Synheart.lastNativeError`, `SynheartNativeException`, `CoreRuntimeBridge.lastCreateError`. Runtime C ABI 2.x accepted; install hints recommend runtime 0.38.0. Research mode forwards raw phone motion by default. Requires `synheart_behavior` 0.4.1 (50 Hz Android accelerometer; merges a notification listener service and `READ_PHONE_STATE`).
0.16.1	`SynheartInstance.createAsync`. Requires `synheart_wear` 0.5.1.
0.16.0	`Synheart.ingestStatus()`, `labEnsureMetadataAsync`, `WearConfig.autoStartPlatformHealth`.
0.15.0	`SynheartInstance` can receive every HSI window it completes; `Synheart.runtimeBehaviorEventStream`; `HostDeclarations.notificationsObservable`. Requires `synheart_session` ^0.3.0.
0.14.0	Runtime version check at startup; buffered HSI delivery. Breaking: `Synheart.pushContextEvent` takes a `ContextEventInput`. Accelerometer samples are converted to g. Foreground app reporting (`BehaviorConfig.reportForegroundApp`).
0.13.0	Breaking: Device Sync calls that touch the network are now async (`await` them). Added `reattestDeviceAuth()`, `logoutDeviceAuth()`, `ensureDeviceAuthRegisteredOrThrow()`; `reregisterDeviceAuth()` deprecated.
0.12.0	Added device-signed Syni chat and session APIs under `Synheart.syni?.service`, requiring a native runtime of 0.21.0 or later.
0.11.1	Android `compileSdk` raised to 36. `minSdk` is unchanged at 24.
0.11.0	Breaking: the SDK no longer bakes in an API host — set `SYNHEART_BASE_URL`. Added the digital HSI axes and richer `SyncNativeError` reasons. `runtimeDiagnostics()` dropped `lastQuality` and gained `missingSymbols`. `Synheart.deleteCloudData()` now throws `UnsupportedError`; use `requestDataDeletion()` with `wipeLocalData()`.

The bundle-secret configuration fields — SynheartConfig.capabilityToken and .capabilitySecret, CloudConfig.apiKey, and ConsentConfig.appApiKey — are deprecated and pending removal. The native runtime dropped bundle-secret configuration as a security fix, so these values are no longer forwarded to it. Use deviceAuthConfig instead, and never ship an API key or signing secret inside an application bundle. See the changelog for the full list.

Advanced APIs

The package also provides:

local session storage and retention;
cross-device sync and baseline transfer;
sleep, recovery, readiness, resilience, and breathing models;
Apple Health and Health Connect backfill;
watch-to-phone EdgeIngest;
lab protocols and research-study enrolment;
secondary SynheartInstance runtime handles;
Syni adaptive AI integration.

Start with the lifecycle above. Integrate advanced APIs only when your product needs them:

Architecture

Runtime, modules, and data flow

Consent System

Consent channels and JWT lifecycle

Scoring Models

Sleep, recovery, and readiness

Health Backfill

Historical HealthKit and Health Connect import

What this SDK does

Requirements

Installation

1. Add the Flutter package

2. Install the native runtimes

3. Configure the platforms

iOS

Android

Start here

Initialization

When the health permission prompt appears

Modes

Running without cloud credentials

Consent

Local development consent

Feature activation and sessions

Reading HSI

Typed state

Canonical JSON

Raw source streams

Personal baselines and daily scores

Production device authentication

Endpoints

Cloud upload

Syni chat and sessions

Errors and diagnostics

Threading

Testing

Flutter example application

Upgrading

Advanced APIs

Architecture

Consent System

Scoring Models

Health Backfill

Resources