Integrating HealthKit and Health Connect Into a Fitness App

A fitness app needs to display recorded workouts on iOS and Android. The initial requirement sounds simple: request access, retrieve activity, and show a useful summary.

The engineering work starts when the data is incomplete, permission changes, or several sources describe overlapping activity.

HealthKit and Health Connect serve related purposes, but their authorization workflows, record models, and update mechanisms differ. A consistent user experience needs to preserve those differences behind a clear application interface.

Understanding HealthKit and Health Connect

Apple HealthKit

HealthKit is Apple’s framework for working with supported health and fitness data.

Read and write access are separate. An app that displays existing workouts does not automatically need permission to save workouts.

HealthKit also limits what an app can determine about read authorization. An empty response does not prove that the user denied access: there may simply be no accessible records matching the query.

Avoid presenting “permission denied” when the platform has not supplied that information.

Android Health Connect

Health Connect allows compatible Android applications to read and write supported health and fitness records with user permission.

Android 14 and later include Health Connect as a system component. Supported earlier environments use the separately installed Health Connect application.

Check service and feature availability at runtime. An Android version check alone does not establish that every required capability is available.

Health Connect is also distinct from the Google Health API. Verify which integration route matches your data sources and product requirements.

What Cross-Platform Support Actually Means

Neither platform automatically moves records between iOS and Android.

Account-based history across devices requires a separate synchronization design if your product needs it.

Define the Required Data Before Writing Integration Code

Start with a feature-to-data map.

“Display activity” could mean daily steps, workout sessions, distance, exercise duration, heart-rate samples, or energy estimates. Those requirements lead to different queries and presentation rules.

For each metric, document:

• Its product purpose.
• The exact supported platform type.
• Whether the feature needs reading, writing, or both.
• Units and reporting intervals.
• Expected source information.
• Missing-data behavior.

Distinguish active energy from total energy. Do not treat a heart-rate sample series as interchangeable with a workout average.

A fitness app data collection checklist can help structure these decisions before permissions and storage are implemented.

Configure Permissions Around the Feature

HealthKit Setup

Enable the HealthKit capability and verify the required entitlements for your target.

Configure the relevant purpose strings:

• NSHealthShareUsageDescription explains reading health data.
• NSHealthUpdateUsageDescription explains writing health data.

Request only the types needed by the feature.

Completion of the authorization request does not establish that every requested read type was granted. Treat authorization-flow completion and successful data retrieval as separate events.

Health Connect Setup

Use the androidx.health.connect:connect-client dependency and select a release appropriate to your requirements.

Declare the required record permissions in AndroidManifest.xml. Implement the prescribed permission rationale and privacy-policy entry points for your supported Android environments.

For Google Play distribution, ensure requested access matches the relevant Console declarations.

Background reads and extended historical access have additional requirements. Do not assume basic read permission provides either.

Keep the Shared Experience Honest

The following is application pseudocode, not a native SDK implementation:

when user enables workout import:
    check platform availability
    check required feature availability

    if unavailable:
        explain the limitation
        keep unrelated features usable
        stop

    explain the requested access
    run platform-specific authorization

    attempt data retrieval

    display records,
    an appropriate empty state,
    or a recoverable error

On HealthKit, avoid inventing a readable permission status that the platform deliberately does not expose.

On Android, check granted permissions before access and handle revocation during operations.

Separate Native Access From Shared Business Logic

One possible architecture uses:

1. Native adapters for authorization and queries.
2. An application-facing interface for supported operations.
3. Normalization for genuinely equivalent fields.
4. Storage and synchronization where required.
5. Presentation that preserves source context.

These can be modules inside one application. They do not need to become separate backend services.

For React Native and Flutter projects, verify that the chosen integration exposes the metadata and update behavior you need. Framework choice does not remove native responsibilities.

Include those requirements in your React Native versus Flutter fitness app evaluation.

Preserve Provenance During Normalization

This JSON is illustrative application data, not a native platform response:

{
  "platform": "health_connect",
  "sourceRecordId": "example-record-id",
  "originApplication": "example.source.app",
  "kind": "workout",
  "startedAt": "2026-10-15T17:00:00Z",
  "endedAt": "2026-10-15T17:35:00Z",
  "startOffsetSeconds": 3600,
  "distanceMeters": null
}

The simplified structure intentionally omits many native fields.

Preserve source identifiers, origin information, available timestamp offsets, and measurement meaning.

A missing distance remains null. Converting it to zero would make a claim the source did not provide.

Also distinguish repeated imports from overlapping recordings. Reimporting the same source record should not create another workout. Two independently recorded workouts require a separate reconciliation policy.

Read and Write Records Carefully

Bound queries to a defined date range and handle pagination, empty responses, and interrupted operations.

Choose raw records or aggregation according to the feature. For Health Connect cumulative types such as steps, use the documented aggregation approach rather than blindly adding raw records from multiple sources.

Daily totals and individual source records answer different questions.

Writing needs its own design:

• Request write access only when required.
• Keep app-created records identifiable.
• Make retries idempotent.
• Preserve the relationship between an app event and its platform record.
• Prevent imported activity from being written back as a new event.

For broader source and access planning, review fitness app wearable integration requirements.

Design Synchronization for Recovery

Initial import and ongoing synchronization are different tasks.

Define an initial history window, then select the appropriate platform mechanism for subsequent changes.

Health Connect supports a changes-token workflow. HealthKit provides anchored queries for supported incremental retrieval. Verify deletion handling, cursor or anchor persistence, and recovery against the exact APIs used.

Treat synchronization as a recoverable operation:

1. Retrieve a batch.
2. Apply changes idempotently.
3. Process deletions.
4. Persist progress safely.
5. Resume without skipping work after interruption.

Plan for expired synchronization state, unavailable inputs, revoked permissions, and delayed upstream records.

A wearable workout data handling strategy should define duplicates, missing information, and source ownership before these cases reach production.

Background execution is conditional. Do not promise uninterrupted real-time updates.

Display data freshness separately from connection status.

Keep Privacy Controls in the Architecture

An on-device summary may not require a server copy. A coach dashboard or account-based history may justify backend storage, with additional responsibilities.

Document:

• What leaves the device.
• Which users and services can access it.
• How credentials and stored records are protected.
• What enters analytics and crash reporting.
• How long records remain.
• How deletion and disconnection work.

Avoid logging raw health payloads, tokens, or identifying activity details in routine diagnostics.

Permission revocation stops future unauthorized access. Define separately how previously imported records are handled.

Assess fitness app privacy and compliance requirements against the actual product and jurisdiction. Using either platform does not automatically establish legal or platform-policy compliance.

Test Each Platform Before Testing the Shared Experience

A successful query proves only part of the feature works.

Use fixtures for normalization tests and device-level checks for permissions, lifecycle behavior, and native integration.

Include these cases in your fitness app integration testing plan.

Transfer correctness is separate from measurement accuracy. Importing a value correctly does not establish that the wearable measured accurately. Evaluate fitness tracker accuracy separately when making measurement claims.

Common Mistakes to Avoid

• Requesting broad permissions without a feature-level purpose.
• Assuming equivalent metrics have identical semantics.
• Embedding native permission behavior in shared business logic.
• Treating missing values as zero.
• Dropping source identifiers and provenance.
• Summing overlapping records without an aggregation policy.
• Assuming background updates are immediate.
• Retrying writes without duplicate protection.
• Logging sensitive records unnecessarily.
• Testing only the successful authorization path.

Each should have a corresponding design decision or test, rather than remaining a general warning in project documentation.

A Practical Implementation Roadmap

Stage 1: Define One Useful Flow

Choose the feature, exact data types, reporting period, and supported environments.

Stage 2: Verify Native Requirements

Review current official documentation, SDK releases, configuration, permissions, and distribution policies.

Stage 3: Implement Minimal Native Adapters

Build one high-priority read flow on each platform before expanding the abstraction.

Stage 4: Establish Data Semantics

Define identifiers, units, timestamps, provenance, aggregation, and missing-data behavior.

Stage 5: Add Recoverable Synchronization

Implement updates, deletions, checkpoints, retries, and stale-data presentation.

Stage 6: Review Privacy and Test Failures

Inspect storage, access, telemetry, retention, and recovery behavior.

Stage 7: Release With Monitoring

Track operational failures without exposing sensitive records. Expand supported types after the initial flow is reliable.

Final Developer Checklist

• [ ] Features map to exact supported platform types.
• [ ] SDK and feature availability are verified.
• [ ] Permissions match actual read and write operations.
• [ ] Native adapters preserve platform differences.
• [ ] Normalization retains provenance and timestamp context.
• [ ] Missing values remain distinct from zero.
• [ ] Queries handle pagination and empty results.
• [ ] Aggregation and duplicate rules are documented.
• [ ] Writes are protected against retry duplication.
• [ ] Synchronization handles updates and deletions.
• [ ] Privacy controls cover storage, access, and logging.
• [ ] Device tests cover revocation and recovery.
• [ ] Maintenance and monitoring have assigned owners.

Conclusion

HealthKit and Health Connect integration requires a clear contract between native platform behavior and the shared fitness experience.

Start with one defined data flow. Preserve provenance, handle missing information honestly, and make updates recoverable.

Expand after permissions, normalization, synchronization, and testing work together.

Which issue has been hardest in your integration: permissions, overlapping records, background updates, or time handling?

This article was prepared with AI assistance.