Every question the Watch Apps pages answer
The 17 watch apps pages answer 55 named questions between them. Every one is listed below, and every link lands on the paragraph that answers it rather than the top of the page.
Anatomy of a watchOS Workout App
- Which object owns what between HKWorkoutSession and HKLiveWorkoutBuilder?The session is the live half and the builder is the record. Apple describes HKWorkoutSession as a session that tracks a person's workout,…
- Does elapsedTime on a live workout builder subtract the time a workout spent paused?No. Apple documents the property as the elapsed time for the workout based on the builder's current contents, including pauses. If your…
- What does shouldCollectWorkoutEvents change about a saved watchOS workout?Apple documents it as a Boolean value that determines whether the workout builder automatically adds events generated by the workout…
HealthKit on Apple Watch: What Changes on the Wrist
- Does a watchOS app learn whether the user allowed reading a health type, when an iPhone app cannot?No, and you should build for that. Across Apple platforms the system withholds read-permission status so that an app cannot infer whether…
- During a workout, should a watch app query the HealthKit store for heart rate or take it from the session?Take it from the session. HealthKit is a store rather than a live feed, so querying it repeatedly during exercise spends power without…
- When does a watchOS workout actually get written into HealthKit?As it happens, then finalized at the end. Apple describes HKLiveWorkoutBuilder as a builder object that constructs a workout incrementally…
Background Execution on Apple Watch: Two Mechanisms
- Which extended runtime type should a training app enable in Background Modes on watchOS?None of them. Apple documents that each app supports a single type of extended runtime session — self care, mindfulness, physical therapy,…
- Can one watchOS app declare both mindfulness and physical therapy extended runtime sessions?No. Apple's wording is that each app can support a single type of extended runtime session, chosen from self care, mindfulness, physical…
- What can a watchOS app keep doing after the screen turns off during an extended runtime session?Apple documents that with extended runtime sessions the app continues to run after the user stops interacting with it, and that it can…
WorkoutKit: Scheduling Workouts Into Apple's Workout App
- Which composition types does WorkoutKit provide for describing a workout?Apple documents four. CustomWorkout is described as a structured interval workout with a series of steps containing custom goals and…
- Where does a scheduled WorkoutKit composition show up for the user?In Apple's Workout app. Apple documents that you can create and maintain a workout schedule and, with the user's permission, sync scheduled…
- What OS versions do I need before WorkoutKit is available?Apple lists WorkoutKit availability from iOS 17.0, iPadOS 17.0 and Mac Catalyst 17.0, together with watchOS 10.0. Anything below those…
Mirroring an Apple Watch Workout to iPhone
- When a workout is mirrored, which device should hold the authoritative session state?The watch, in our judgement, because that is where the session and the sensors are and where Apple's one-session-at-a-time rule applies.…
- Can Siri pause or cancel a workout that my own app started on Apple Watch?Apple documents that workout sessions support Siri control for starting, pausing, resuming and canceling. The practical consequence is that…
- What should the iPhone display if it loses contact with the watch mid-session?Something honest about what it does and does not know. The workout is running on the wrist, so it continues regardless of what the phone…
Wear OS Fitness App Anatomy: Standalone or Not (2026)
- Where does a Wear OS app declare that it is standalone, and what happens if the value is wrong?It is a meta-data entry named com.google.android.wearable.standalone in the watch app's manifest, set to true or false. Google's…
- Can a Wear OS watch app be installed before the phone app it depends on?Yes. Google documents that even if the value of com.google.android.wearable.standalone is false, the watch app can be installed before the…
- How should a Wear OS fitness app handle sign-in when the paired phone is an iPhone?Assume you cannot detect the phone side at all. Google's documentation states that from Wear OS you cannot programmatically determine…
Wear OS Exercise Tracking with Health Services (2026)
- Do Health Services exercise goals replace the target-checking logic in my own Wear OS code?For the cases the platform models, our judgement is yes, and you should delete the duplicate. Google documents ExerciseClient as able to…
- Should the watch or the phone own a Wear OS workout session?The watch, because that is where Health Services and the sensors are. The exercise runs on the device, exercise state updates originate…
- Which Wear OS versions can run a Health Services exercise app, and what about older watches?Google documents Health Services as a platform service on Wear OS 3 and later, and its ExerciseClient and PassiveMonitoringClient APIs come…
Wear OS Tiles for a Fitness App (2026)
- Can I build a Wear OS tile with Jetpack Compose, and can users scroll it?No to both. Google's documentation states that tiles are built declaratively using Jetpack's protolayout and tiles libraries rather than…
- Where should a Wear OS tile get its data, given that it renders in a separate process?From local storage that something else keeps up to date. Google's documentation states that tiles render in a separate, remote environment…
- Should a fitness tile show a workout summary or a start button?Our judgement is a start button for the specific workout this person actually does, plus one figure for today. Google's framing is that a…
Wear OS Phone Sync: The Data Layer and Its Limits (2026)
- Does the Wear OS Data Layer work when the watch is paired to an iPhone?No. Google's documentation states that the Data Layer API can send messages and synchronize data only with phones that run Android or with…
- Can I use DataItem storage as my Wear OS app's local database?No, and Google says so directly: the class is meant to synchronize data and not serve as a storage mechanism, and its guidance is to create…
- Should a Wear OS fitness app upload workouts from the watch or hand them to the phone?From the watch. Google's guidance is to make network calls from the watch as you would from a phone, precisely because the phone link is…
watchOS vs Wear OS: Building the App That Runs on the Watch
- If we already ship an HKWorkoutSession app, what is the Wear OS equivalent we build against?Health Services, and specifically ExerciseClient. On Wear OS 3 and later, Health Services sits between apps and the sensors and algorithms…
- Is a watchOS complication the same kind of surface as a Wear OS tile?They serve a similar purpose and are built nothing alike. Apple's complications come from WidgetKit, appear on the watch face and in the…
- How much of a watchOS fitness app can we reuse when we add Wear OS?Labelled as judgement rather than documentation: reuse the domain model, the scoring and the sync protocol, and expect to write the watch…
Watch App Battery: The Constraint That Decides Scope
- Why does declaring the right workout activity type matter for power on Apple Watch?Because the declaration configures hardware. Apple documents that a workout session fine-tunes Apple Watch's sensors for the specified…
- Is there a lower-power way to keep a long-lived Wear OS feature updating without an active exercise?Yes, and that is what PassiveMonitoringClient is for. Google describes it as receiving updates about a data type or an event, suited to…
- Why won't you publish a figure for how much battery a watch workout app uses?Because we have not measured your app, and neither has whoever published the number you found. Drain depends on which sensors your activity…
Testing Watch Apps Without a Watch on Every Desk
- Can I test watch sensors on the watchOS simulator or the Wear OS emulator?Verify what your simulator or emulator supports today and write the answer down with the tool version beside it, because that surface…
- Which watch behaviors still need a physical device pass before release?Pairing and installation across the combinations you support, including the phone-app-missing state. Reconnection: out of range and back,…
- What should a recorded watch session contain to be useful as a test fixture?Timestamped samples in capture order, each carrying its own timestamp so nothing depends on the clock at replay time, plus a terminal…
CustomWorkout, IntervalBlock and WorkoutScheduler in Swift
- Does WorkoutScheduler.schedule take a Date or DateComponents?DateComponents. Apple declares it as schedule(_ workout: WorkoutPlan, at: DateComponents) async, and describes the parameter as date…
- How many workouts can one app schedule with WorkoutKit?Apple exposes the limit as WorkoutScheduler.maxAllowedScheduledWorkoutCount, a static Int described as the maximum number of workouts your…
- Can an iPhone app call openInWorkoutApp on a WorkoutPlan?Apple's availability metadata for WorkoutPlan.openInWorkoutApp() lists watchOS 10.0 and no iOS version, and describes it as opening the…
- What are the two purposes an IntervalStep can have?Apple's IntervalStep.Purpose enum has two cases: work, described as a work step, and recovery, described as a recovery step. Each…
HKWorkoutSession Lifecycle in Swift: Start, Stop, Save
- Why should I wait for the stopped state before calling endCollection on the workout builder?Because that is the order Apple documents. Its Running workout sessions article says to call stopActivity(with:) and, after the session has…
- finishWorkout returned nil without an error. Did the workout save?Apple says yes. The finishWorkout(completion:) discussion states that the function returns nil if finishing the workout succeeded but the…
- How does a watchOS app get its workout back after crashing mid-session?Apple documents that if the app crashes during a workout session, the system calls the extension delegate's handleActiveWorkoutRecovery()…
- Can an iPhone app run its own HKWorkoutSession with a live workout builder?From iOS 26, according to Apple's availability metadata. The HKWorkoutSession class lists iOS 17.0, but init(healthStore:configuration:),…
startMirroringToCompanionDevice: The Mirrored Workout API
- Why does workoutSessionMirroringStartHandler fire more than once during one workout?Because Apple Watch reconnects after a dropped link. Apple's discussion of the handler says your app may receive multiple calls, that if…
- Can the iPhone send commands to the watch over a mirrored workout session?Yes, as data. Apple documents sendToRemoteWorkoutSession(data:completion:) on iOS 17.0 and watchOS 10.0 and states you can send from either…
- Which OS versions does Apple list for startMirroringToCompanionDevice?watchOS 10.0, and only watchOS: mirroring is started from the watch. The receiving side, HKHealthStore's…
ExerciseClient in Kotlin: Capabilities to endExerciseAsync
- What does ExerciseEndReason AUTO_END_MISSING_LISTENER mean on Wear OS?Health Services ended your exercise because no ExerciseUpdateCallback was registered for five minutes. Google's ExerciseClient reference…
- Which sensors does prepareExerciseAsync actually warm up?Two. Google's reference for prepareExerciseAsync(WarmUpConfig) says the sensors available for warmup are GPS, as DataType.LOCATION, and…
- Should a Wear OS workout request DISTANCE or DISTANCE_TOTAL?Whichever your screen shows, and usually DISTANCE_TOTAL for a running total. Google's DataType reference describes DISTANCE as a distance…
- Why does my Wear OS workout timer jump when the screen turns back on?Because updates are batched while the screen is off. Google's guide says the processor delivers ExerciseUpdate messages only when awake or…
PassiveMonitoringClient and MeasureClient on Wear OS
- Do Health Services passive data registrations survive a watch reboot?No. Google's Passive data updates guide states that passive data registrations do not persist across reboots. Its documented fix is a…
- Why did my PassiveMonitoringClient stop delivering heart rate after I registered for steps?Because a new registration replaces the old one. Google's reference for setPassiveListenerServiceAsync and setPassiveListenerCallback says…
- Does a MeasureClient heart rate reading also reach my passive listener?Google's MeasureClient reference says existing subscriptions made with PassiveMonitoringClient are also expected to get the data generated…
- What permission does background heart rate need on Wear OS 6?Google's Health Services permissions page says that if your app targets API level 36 or higher and uses PassiveMonitoringClient to access…
Back to the Watch Apps hub, or see every question this site answers.