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
- Activate once per launch (Installing the key).
- Get camera access with
requestCameraPermission().start()never prompts and throwscameraPermissionDenieduntil access is granted. The pre-built flows ask for access themselves. - Subscribe to events. Nothing is replayed and the wrappers do not buffer, so a listener added after
start()misses the first events. - On Android, if you show a preview, mount it and wait for its
onReady: the session binds the view that exists atstart()(Camera preview). - 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 onecancelled. 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 emitsmeasurementComplete 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.
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
lowFrameRatewhile positioning, and the reading waits until it recovers. On iOS the SDK may adjust the capture, which cancels a reading in progress withcancelled(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 withfailed(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"orrequestedOrientation, plusFLAG_KEEP_SCREEN_ON. On large screens Android may ignore the portrait lock, so addandroid:configChanges="orientation|screenSize|smallestScreenSize|screenLayout"to the reading activity to keep it from being recreated. - React Native:
expo-screen-orientation. WithoutVitalsCameraPreviewon screen, keep it awake withexpo-keep-awakeorreact-native-keep-awake. - Flutter:
SystemChrome.setPreferredOrientations. WithoutVitalsCameraPreviewon screen, keep it awake withwakelock_plus. - Capacitor:
@capacitor/screen-orientation, plus@capacitor-community/keep-awake.
Failures
SwiftVitalsError cases, Kotlin VitalsException subclasses of the same names, wrapper code strings
(Errors).