A useful smart watch application does more than receive numbers from a sensor. It knows whether a workout is running, which metrics the watch supports, how old a displayed value is, and what happens when the screen turns off. Those decisions determine whether a person can trust the workout experience.
For a Wear OS application, Health Services provides an important starting point. This guide uses a simple walking workout to explain the path from capability discovery to a saved session. The examples describe application design; they do not imply that WearAPI.com operates a device connection service.
Understand the three data layers
Separate raw sensors, on-watch fitness services, and stored health records. Raw sensor access exposes signals your application must interpret. Health Services sits on the watch and provides activity and exercise metrics using device sensors and platform processing. A phone health store is a different layer for reading and writing records exchanged by applications.
Android's Health Services overview describes this service on Wear OS 3 and higher, including its role in sensor configuration and derived metrics. Availability of the service does not mean that every supported watch produces every possible measurement.
Keep these responsibilities visible in your architecture. The watch records and presents the ongoing workout. Your application saves its own session record. A separate synchronization path can move that record to the phone or another authorized destination. Do not assume the phone's health history will appear simply because the watch received live updates.
The broader smart watch API overview covers other access routes. Apple Watch, proprietary watch platforms, and Wear OS require their own integration decisions.
Choose the client for the experience
Health Services separates three usage patterns. ExerciseClient supports an application managing a workout and receiving exercise state and metric updates. Use that model for a walking session with start, pause, resume, and finish controls.
MeasureClient is intended for short measurements, such as showing a current reading while the person views a screen. Its live callback registration is not the right mechanism for an all-day subscription or workout recorder. Register only for the short interaction and release the callback when it ends.
PassiveMonitoringClient serves longer-lived monitoring with less frequent updates. Its background-oriented pattern is useful when the product can consume data without maintaining an active workout. It should not be used to promise the same display cadence as an active exercise experience.
Start from the interaction rather than whichever sample application seems easiest to copy. A screen that briefly checks a metric should not create a fake workout. A recorded walk needs a coherent exercise lifecycle, even if the first design only displays elapsed time.
Discover capabilities before designing controls
Query capabilities for the client and requested exercise type. Confirm the supported metrics before building the exercise configuration. A broad list of data types in an SDK reference is a vocabulary of possibilities, not the capability profile of the watch on someone's wrist.
For the walking example, classify elapsed time and explicit session controls as core application behavior. Treat heart rate, distance, or other device-provided metrics as features that require support and relevant permission. The launch screen can explain which measurements are available before the person starts moving.
Keep capability and permission failures separate internally. An unsupported metric will not become available after another consent prompt. A supported metric without permission may become available through the appropriate request flow. Avoid repeatedly prompting when the person has chosen to proceed with a simpler workout.
Store a concise capability snapshot with diagnostic events, without copying raw measurements into logs. When a user reports that distance is missing, support can then establish whether that metric was requested and supported for the exercise type.
Model the workout as a state machine
Use explicit states such as ready, preparing, active, paused, finishing, and saved. Add recoverable error paths for a failed start or a lost application process. Buttons should reflect the confirmed state, with a pending state while the platform processes a request.
A double tap on Start must not create two application records. Assign a local session identifier when preparation begins and reuse it throughout the lifecycle. Disable conflicting transitions while a request is pending, then reconcile with the reported exercise state before enabling the next action.
Consider exercise ownership before starting. Another application may already be recording. Choose an interface that explains the situation and uses the platform's supported behavior, rather than silently assuming your app controls the session. Likewise, reopening your own application should investigate an existing session before presenting a fresh Start button.
Pause semantics deserve a written rule. Is the headline timer active exercise duration or wall-clock time since starting? Store both if the feature needs both, and label them accurately. A summary that uses one interpretation while the live display uses another creates an avoidable discrepancy.
Keep live values honest
A callback arrival time is not necessarily the measurement time. Use the timestamps and interval semantics supplied by the API, and follow its documented clock conversion rules. Keep receipt time separately when useful for debugging delivery delays.
For a live heart rate tile, track the most recent measurement and its age. If updates stop, change the presentation after a documented threshold. Showing a dash with “waiting for a reading” is more honest than leaving an old number looking current. The threshold is a product decision to test, not evidence that the person's physiology changed.
Do not turn a missing reading into zero. Do not derive a session average by averaging averages from unequal intervals. Choose an aggregation method that matches the available samples and metric definition, or display the platform's supplied summary with its provenance preserved.
A watch measurement also needs context. A recorded heart rate value alone does not establish a diagnosis or prove that a sensor is accurate for every activity. The heart rate monitor integration page explains the importance of measurement source and intended use.
Save the session before syncing
A finished workout should remain available on the watch even when the phone is unreachable. Persist the session identity, timing, exercise type, available summary, and completion state before depending on a network transfer. Treat the upload as a separate operation that can be retried.
Use an idempotent import key at the receiving side. If the watch sends the same saved session twice after reconnecting, the application should update one workout. Preserve the original record identifier through later exports where possible so copied records remain traceable.
Be deliberate about the amount of data retained. A session summary may serve the product without storing every high-frequency sample. Conversely, a feature that plots a detailed timeline needs enough resolution to support that display. Choose the retention policy from the feature and explain it in the consent experience.
If the phone subsequently writes the workout to a health store, track that write independently from watch-to-phone delivery. “Saved on watch,” “transferred,” and “shared with health store” are distinct states that should not be collapsed into one ambiguous success flag.
Test battery, lifecycle, and recovery
Battery testing should reflect the actual interaction. A continuously visible metrics screen, a wrist-down workout, and a brief spot check create different workloads. Measure a representative session on supported hardware, including display use and communication, before choosing a refresh cadence.
Use synthetic data to check state transitions and transformations, then test physical devices for lifecycle and usability. A smooth emulator demonstration cannot establish real-world measurement availability or battery behavior.
- Start with one optional permission declined and complete a useful workout.
- Pause, resume, and finish while checking timer consistency.
- Turn the screen off and reopen the app during the session.
- Interrupt the application and verify recovery of an ongoing or saved workout.
- Finish with the phone disconnected, then reconnect and confirm one imported record.
- Present unavailable metrics without stale values or invented zeros.
Also test a device with a smaller capability set than your primary development watch. This exposes accidental assumptions about metrics earlier than user reports. For a broader fixture strategy, read the data quality testing guide.
Deliver a workout people can understand
A dependable watch feature has a clear scope: the right client for its interaction, capability-aware configuration, explicit session states, and a durable saved result. Begin with a modest workout that survives interruption and missing data. Add richer metrics when the acquisition path, display meaning, and test evidence support them. The developer checklists can help carry those decisions into implementation reviews.
