HealthKit on Apple Watch: What Changes on the Wrist

Teams that already shipped a HealthKit integration on iPhone tend to assume the watch is the same code in a smaller target. It is the same framework, but the job it does is different enough that copying the phone architecture across produces an app that feels broken: numbers that arrive late and in clumps, a screen that redraws when nothing happened, and a summary that disagrees with the Health app.

The phone-side setup — capability, usage-description keys, authorization, queries and background delivery — is covered in the HealthKit integration guide. This page is only about what is different once the code runs on a wrist.

The store is not the stream, and on the watch that distinction is the whole design#

HealthKit is a store. It is where samples are persisted, authorized, shared between apps and queried after the fact. It is not a live feed, and no query option turns it into one.

During a workout, the live path on Apple Watch is a workout session. Apple documents that the session fine-tunes Apple Watch's sensors for the specified activity and that all workout sessions generate high-frequency heart rate samples. That behavior belongs to the session, not to the store, which is why polling the store harder during a workout changes nothing except battery. The full argument is in Apple Watch live heart rate, and the object-level split is in the anatomy of a watchOS workout app.

The practical rule for a watch app: if a number is on screen while the user is moving, it comes from the session. If a number describes something that already finished — this week's workouts, yesterday's resting heart rate, the last time they trained legs — it comes from the store.

Authorization on the watch#

Authorization uses the same HKHealthStore API surface as on iPhone, including the availability guard and the usage-description strings that must exist before you ever call the authorization API. There is no separate watch-only permission system to learn.

What we cannot tell you from Apple's documentation as read this session is the exact behavior of a grant made in your iPhone app with respect to your watchOS target under every project configuration. Treat that as something to confirm against current Apple documentation and to verify on hardware for your own target layout, rather than something to assume. The design consequence is the same either way: never let the watch app's first useful screen depend on authorization having already happened somewhere else. A watch app that renders an empty ring and no explanation because a grant did not carry across is indistinguishable, to the user, from an app that is broken.

Read denial is invisible, and that has not changed#

This is the point that catches every HealthKit integration and it is worth repeating on the watch, where the screen is small enough that a wrong assumption becomes a blank face. To avoid leaking whether somebody has health data at all, the system does not report whether the user granted or denied read access. Authorization status reliably reflects write and share access; for read types it typically comes back as not determined even after a grant.

So a successful authorization call means the sheet was shown, not that reading will work. The documented pattern is to run the query and treat an empty result as "no data or no permission," because those two states are deliberately indistinguishable. On the watch this means every screen that displays stored data needs an honest empty state, and none of them should be gated on a read-permission check that cannot answer the question.

Writing the workout at the end#

The write is not a separate sync job you schedule. Apple documents HKLiveWorkoutBuilder as "A builder object that constructs a workout incrementally based on live data from an active workout session," and states that you "use a live workout builder to create an HKWorkout sample during an active HKWorkoutSession." The sample accumulates as the workout happens and is finished when the session finishes.

Two consequences worth designing for. First, ending is a moment with work in it — the session stops, the builder is finished, the sample is saved — and any of those steps can fail on a device that is about to be put on a charger. Second, because Apple documents that a session can end when a second workout starts, the ending can be unsolicited, and your save policy has to cover the untidy case as well as the tap on your own stop button.

Reading the store from the watch#

Stored data is still available on the wrist, and the interesting question is what is worth showing there. Our judgement: a watch screen has room for one comparison, not a dashboard. Last week's total, the last session of this type, or the current streak reads well; a scrollable history does not, and it costs a query on a device where you are budgeting power for the workout itself.

Anything you do query, query at a coarse grain and cache the answer for the length of the session. The reconciliation questions do not go away just because the screen is small: a phone and a watch that both write the same activity produce overlapping samples, which is deduplicating health data, and anything summarized per day inherits the boundary problem in time zones and day boundaries.

What belongs on the phone instead#

A useful test when you are deciding where a feature lives: does it need to be read at arm's length while somebody is out of breath? If not, it probably belongs in the phone app, where there is room, a keyboard and no power budget competing with a sensor stack. Long history views, program editing, account settings and anything with meaningful text entry are phone work. Getting a coach's program onto the watch without your app being open is its own mechanism — WorkoutKit scheduled workouts — and keeping the app alive while the wrist is down is background execution.

Testing it#

HealthKit behavior that depends on real permission states and real samples is hardware work; a simulator will happily let you build a screen that no real user ever sees. Cover the store-facing logic behind a seam with recorded samples in CI, and reserve device passes for the three states that actually bite: a fresh install with nothing granted, a grant with no data behind it, and a denial that looks identical to the second case. Mocking wearable data covers building those fixtures.