public final class SensorSessionOptions

Whether received samples are written through to the platform health store. Defaults to false, and that default is deliberate.

During a workout on watchOS – and on iOS 26 and later – the operating system records heart rate into HealthKit itself. A strap that also writes its own heart-rate samples then produces two overlapping sets for the same minutes, and every downstream average, maximum and chart is computed over double-counted data.

This release drives no live workout session, so that overlap comes from a workout the user started elsewhere – in Apple’s own Workout app, say – rather than from one of yours. The default stays false regardless: turning it on is a decision about somebody else’s data as much as your own.

If you are recording a workout, attach the session to it with setWorkoutSession(WorkoutSession) instead: samples land in the workout’s statistics and are persisted once, as part of the workout, when it ends.

Turning this on is right when you are logging a standalone measurement the OS knows nothing about – a weight from a scale, a body temperature from a thermometer, a glucose reading from a meter.

Blood pressure is not among them on mobile in this release. It is two values in one reading, which HealthKit models as a correlation and Health Connect as its own record type, and neither is implemented here – the sample line this API writes over carries a single value. A cuff reading routed to the store therefore fails with HealthError.TYPE_NOT_SUPPORTED on both platforms rather than being quietly dropped, and the local and simulator stores keep it fine. Read it off the session and persist it yourself until the correlation paths land.

How long samples are batched before a store write.

The Duration form of setStoreBatchMillis(int), which is the type the rest of the framework speaks; the millis form stays for the ports and the wire format.

Attaches this sensor to a workout, so its samples become part of that workout’s statistics and are persisted with it.

This is the right way to feed a heart-rate strap into a recorded workout – see the warning on setWriteToStore(boolean).

How old a sample may be before it is dropped.

The Duration form of setStaleSampleMillis(int), which is the type the rest of the framework speaks; the millis form stays for the ports and the wire format.