Skip to main content
A session runs until it delivers one reading. It turns the camera and torch on, waits for a steady fingertip, measures for 60 seconds, checks the reading and turns the camera off. The events are the same on iOS, Android and in the wrappers. There is no configuration: every session runs the validated 60-second reading with the NEUROFIT app’s settings.
React Native, Flutter and Capacitor: there is no session object. start() begins one, and you call start() again to retry. Events arrive on the JavaScript or UI thread (Threads).

Phases

Cancels, failed quality checks and interruptions return the session to positioning by itself. Only a result or the errors under Failures end it.

Starting a session

  1. Activate once per launch (Installing the key).
  2. Get camera access with requestCameraPermission(). start() never prompts and throws cameraPermissionDenied until access is granted. The pre-built flows ask for access themselves.
  3. Subscribe to events. Nothing is replayed and the wrappers do not buffer, so a listener added after start() misses the first events.
  4. On Android, if you show a preview, mount it and wait for its onReady: the session binds the view that exists at start() (Camera preview).
  5. Call start().
start() throws (or rejects) only when a precondition fails: notActivated, licenseInvalid (a trial key past its end), cameraPermissionDenied, unsupportedDevice or invalidUsage. The session then stays idle, so fix the cause and call start() again. A camera that cannot be opened arrives after start() returns, as failed(cameraUnavailable). Every code: Failures. A trial key’s end is checked only by activate and start(), so a session that has started runs to its end.

Events

When the stream ends. The iOS AsyncStream and the Android Flow end at the same points: after completed, after failed, and after stop() (after the outcome, when you stop while finalizing). Android also ends it when the lifecycle owner is destroyed. A collector that starts after the end finishes at once with no events. Android keeps 64 events per collector and drops the oldest when a collector falls behind, so the outcome always arrives. Threads: iOS, Android, wrappers. Minor releases may add events, so keep a default branch (Versioning).

Positioning

Once the signal is steady, startProgress fills over a few seconds and the reading starts by itself. There is nothing to call, and cancelReading() does nothing here. Kotlin names are UPPER_SNAKE_CASE (NO_CONTACT). The core SDKs return values, not text: VitalsStrings’s guidanceText(guidance, hasTorch) returns the pre-built flow’s English text for a value (flow defaults).

Holding the start

isAutoStartEnabled is true by default (setAutoStartEnabled from Java and in the wrappers). While it is false, positioning goes on, with the camera, torch and guidance running and startProgress filling, but no reading starts. Use it while something covers the reading screen, such as an intro or a coaching sheet. A reading already measuring is unaffected, and after its cancel the session waits. Set it back to true and the next steady moment starts the reading. You can set it at any time, before start() too. On iOS and Android it belongs to the session. In the wrappers, setAutoStartEnabled(false) before start() holds that session, and the setting goes back to true when the session ends (stop(), completed or failed). The hold is also how you pause after failed checks.

Measuring

The session abandons an attempt it cannot finish reliably rather than run the full minute for no result, and every abandoned attempt gets one cancelled. VitalsStrings’s cancelNotice(reason) returns the flow’s notes. The next reading then starts by itself once the signal is steady, unless you hold the start.

Live preview

LivePreview arrives about once per second while measuring. The first one of each attempt follows started at once, with progress 0 and no values, so your live UI can open at 0%. signalQuality describes the live signal while measuring. The result’s quality grades the finished reading.

Finalizing

After 60 seconds the session emits measurementComplete and checks the reading, usually within 1 to 3 seconds, torch still on. Then: An unexpected error ends the session with failed(internalError) instead. No retry limit. Every failed reading gets its own cancel. Your app decides when to pause, for example after three in a row, as the pre-built flow does. Pause after failed checks. To show your own screen before the next attempt, set the hold to false when measurementComplete arrives, on every platform. Not on cancelled: the next reading may start before a hold set then takes effect. If the reading completes, the session ends as usual. If it fails the check, the session waits in positioning, camera and torch on: set the hold back to true to try again, or call stop(). stop() never loses a finished reading. After measurementComplete, stop() turns the camera and torch off at once, and the session still delivers completed(result) or cancelled(qualityCheckFailed), then ends. On iOS the session keeps itself alive until it has delivered, even if you drop your reference. Keep your subscription until then. A stop() while positioning or measuring ends the session without a result.

Interruptions and camera health

An interruption pauses the capture without ending the session:
  • iOS: the app moving to the background, a phone call, Split View or Slide Over, another app using the camera, system pressure, or a media-services reset.
  • Android: the lifecycle owner’s ON_STOP, or another app taking the camera.
A reading in progress gets cancelled(interrupted). The session waits in positioning with no guidance and restarts the capture by itself when the cause clears. An interruption after measurementComplete does not affect the result. A wait the system controls, such as another app holding the camera, has no time limit. Once the SDK is restoring the capture in the foreground, it gives up after 10 seconds with failed(cameraUnavailable). Android also stops the session when the lifecycle owner is destroyed.
  • Frame rate. A slow camera shows lowFrameRate while positioning, and the reading waits until it recovers. On iOS the SDK may adjust the capture, which cancels a reading in progress with cancelled(interrupted). A low frame rate never ends a session.
  • Stalls. A camera that stops delivering frames is restarted once, and a reading in progress gets cancelled(interrupted). A second stall in the same session ends it with failed(cameraUnavailable).

Orientation and screen

Keep the reading screen in portrait and awake for the whole minute. Some entry points do both for you: For your own screens (VitalsCameraPreview keeps the screen awake while it shows):
  • iOS: UIApplication.shared.isIdleTimerDisabled = true, and portrait in the orientations your scene or view controller supports.
  • Android: android:screenOrientation="portrait" or requestedOrientation, plus FLAG_KEEP_SCREEN_ON. On large screens Android may ignore the portrait lock, so add android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout" to the reading activity to keep it from being recreated.
  • React Native: expo-screen-orientation. Without VitalsCameraPreview on screen, keep it awake with expo-keep-awake or react-native-keep-awake.
  • Flutter: SystemChrome.setPreferredOrientations. Without VitalsCameraPreview on screen, keep it awake with wakelock_plus.
  • Capacitor: @capacitor/screen-orientation, plus @capacitor-community/keep-awake.
Why: in a native Android app a rotation or resize recreates an activity that does not declare those changes, which stops the session. In React Native, Flutter and Capacitor apps the activity survives, but the layout jumps mid-reading. On iOS a rotation can briefly interrupt capture. On every platform, a screen that locks interrupts the reading.

Failures

Swift VitalsError cases, Kotlin VitalsException subclasses of the same names, wrapper code strings (Errors).