Skip to main content

HealthSync iOS app support

Get help with the HealthSync iOS app for syncing Apple Health data to your dashboard.

Getting started​

New to HealthSync? Start with the main documentation:

Quick setup checklist​

  1. Install the app from the App Store
  2. Grant HealthKit permissions when prompted
  3. Open Settings in the app
  4. Enter your dashboard API URL (e.g., https://stats.example.com)
  5. Enter your API key
  6. Tap "Test Connection" to verify
  7. Select your sleep tracker (e.g., Oura) in the Sleep Preferences section
  8. Return to main screen and tap "Sync Now"

Common issues​

HealthKit shows red X​

Symptom: Main screen shows "HealthKit: Not authorized" with a red indicator.

Solutions:

  1. Tap "Request Health Access" in the App
  2. In the Health permissions sheet, enable all data types
  3. If already granted, check iPhone Settings > Privacy > Health > HealthSync

Note: iOS does not reveal whether read-only access was granted. If you've approved permissions, the App should work even if the indicator shows red initially.

Dashboard API shows "Not configured"​

Symptom: Main screen shows "Dashboard API: Not configured".

Solutions:

  1. Open Settings (gear icon)
  2. Enter your full API URL including https://
  3. Enter your API key exactly as configured on your server
  4. Tap "Test Connection" - should show green checkmark

Sync Now button is greyed out​

Symptom: Cannot tap the Sync Now button.

Causes:

  • HealthKit permissions not granted
  • API endpoint not configured
  • Sync already in progress

Solution: Ensure both HealthKit (green checkmark) and Dashboard API (green checkmark) show as connected on the main screen.

Connection test fails​

Symptom: "Test Connection" shows red X or error message.

Check:

  • API URL is correct and accessible from your phone
  • API key matches the DAEMON_API_KEY environment variable on your server
  • Your server is running and the /api/import/health-app endpoint exists
  • Your phone has internet connectivity

Data not appearing in dashboard​

Symptom: Sync completes but data doesn't show in dashboard.

Check:

  1. Verify sync completed successfully (check upload count in Settings)
  2. Dashboard may show "Yesterday's Activity" - today's data appears tomorrow
  3. Check your server logs for import errors
  4. Verify database has the records (check import_logs table)

Background sync not working​

Symptom: App doesn't sync automatically in background.

Requirements:

  • App must be opened at least once after iPhone restart
  • Background App Refresh must be enabled (Settings > General > Background App Refresh)
  • iPhone must not be in Low Power Mode

Note: iOS controls background refresh timing. It may take 15-60 minutes between syncs, and iOS may delay syncs based on battery and usage patterns.

API endpoint requirements​

Your dashboard API must:

RequirementDetails
HTTPSSecure connection required
POST endpoint/api/import/health-app
AuthenticationBearer token in Authorization header
ResponseJSON with import counts

Example endpoint response:

{
  "imported": {
    "sleep": 2,
    "metrics": 2,
    "workouts": 1
  }
}

Data sync details​

What data is synced​

Data typeSync period
SleepConfigurable: 1, 3, 7, 14, or 30 days (background sync uses 3 days)
Daily metricsConfigurable: 1, 3, 7, 14, or 30 days
WorkoutsConfigurable: 1, 3, 7, 14, or 30 days

Sleep data is filtered to the source selected in Settings (e.g., Oura only) to prevent duplicate data from multiple devices.

Sync frequency​

TriggerFrequency
ManualTap "Sync Now" anytime
BackgroundEvery 15-60 minutes (iOS controlled)
HealthKit updateWhen new health data arrives

Reporting issues​

Before reporting​

  1. Check the troubleshooting steps above
  2. Try closing and reopening the App
  3. Try restarting your iPhone
  4. Check your server logs for errors

How to report​

For bugs or feature requests:

  1. Note your iOS version and iPhone model
  2. Describe what you expected vs what happened
  3. Include any error messages shown
  4. Contact via the methods below

Contact​

For App Store reviewers​

If you are reviewing this app for App Store submission:

Quick reference​

ItemLocation
HealthKit statusMain screen, first row ("HealthKit" with green/red indicator)
Health data syncMain screen, "Sync Now" button
Sleep tracker pickerSettings screen, "Sleep Preferences" section
Sleep debt thresholdSettings screen, "Sleep Preferences" section
Upload statisticsSettings screen (gear icon), "Statistics" section
API configurationSettings screen, "Dashboard URL" and "API Key" fields

How to test​

  1. Open the app
  2. Tap "Request Health Access" and grant all permissions
  3. Go to Settings and enter any HTTPS URL (e.g., https://httpbin.org/post)
  4. In Settings, observe the "Sleep Preferences" section - the Sleep Tracker picker shows sources discovered via HealthKit (e.g., Oura, Apple Watch, iPhone)
  5. Return to main screen - "HealthKit" should show green checkmark
  6. Tap "Sync Now" to see health data being read and transmitted

About this app​

This app is designed for developers who self-host their own dashboards. It reads health data from the Health app and syncs it to a user-configured API endpoint. The app developer does not receive any health data.