DataSync

A comprehensive health data synchronization system for React Native applications that provides seamless integration with Apple Health and Android Health Connect. The DataSync module enables automatic syncing of health measurements to FHIR-compliant healthcare systems with robust authorization, progress tracking, and error handling.

Import this module from @ovok/native/data-sync; it is intentionally not part of the root package entry point. The Health data guide is the canonical integration walkthrough. This page is the module map and native configuration reference.

Prerequisites

Before using the DataSync module, you must configure the required permissions and plugins in your app.config.ts:

Android Health Connect Configuration

// app.config.ts
export default {
  android: {
    permissions: [
      // Health Connect Read Permissions
      "android.permission.health.READ_BODY_TEMPERATURE",
      "android.permission.health.READ_WEIGHT",
      "android.permission.health.READ_OXYGEN_SATURATION",
      "android.permission.health.READ_STEPS",
      "android.permission.health.READ_RESTING_HEART_RATE",
      "android.permission.health.READ_HEART_RATE_VARIABILITY",
      "android.permission.health.READ_HEART_RATE",
      "android.permission.health.READ_RESPIRATORY_RATE",
      "android.permission.health.READ_VO2_MAX",

      // Health Connect Write Permissions (optional)
      "android.permission.health.WRITE_WEIGHT",
      "android.permission.health.WRITE_BODY_TEMPERATURE",
      "android.permission.health.WRITE_OXYGEN_SATURATION",
      "android.permission.health.WRITE_STEPS",
      "android.permission.health.WRITE_RESTING_HEART_RATE",
      "android.permission.health.WRITE_HEART_RATE_VARIABILITY",
      "android.permission.health.WRITE_HEART_RATE",
      "android.permission.health.WRITE_RESPIRATORY_RATE",
      "android.permission.health.WRITE_VO2_MAX",
    ],
  },
  plugins: [
    "expo-health-connect", // Required for Android Health Connect
  ],
};

iOS HealthKit Configuration

// app.config.ts
export default {
  ios: {
    infoPlist: {
      NSHealthShareUsageDescription:
        "Allow access to your health data for personalized insights",
      NSHealthUpdateUsageDescription:
        "Allow the app to update your health data",
    },
  },
  plugins: [
    [
      "@kingstinct/react-native-healthkit",
      {
        NSHealthShareUsageDescription:
          "We need access to your step count data to track your daily activity",
        NSHealthUpdateUsageDescription:
          "We need access to update your health data",
        background: true, // Enable background health data processing
      },
    ],
  ],
};

Important: You only need to include permissions for the health data types your app actually uses. Including unnecessary permissions may delay App Store review.

Key Features

• Multi-Platform Support: Native integration with Apple Health (iOS) and Android Health Connect
• FHIR Compliance: Automatic conversion of health data to FHIR Observation resources
• Authorization Management: Streamlined permission handling with customizable UI flows
• Network Policy: Optional Wi-Fi-only pausing controlled by the wifiOnly prop (default false)
• Pause/Resume: Automatic pause/resume of sync when network is not available or whenever you want to pause the sync
• Progress Tracking: Real-time sync progress monitoring with detailed status reporting
• Background delivery: Apple HealthKit observer delivery when configured; Android process-death scheduling is documented separately
• Manual Request UI: Customizable bottom sheet for manual authorization requests
• Error Handling: Comprehensive error management with bounded transient-save retries
• Type Safety: Full TypeScript support for health data types and sync operations

Architecture Overview

The DataSync module follows a compound component pattern with platform-specific implementations:

Core Components

1. DataSync Container: Main compound component that provides access to platform-specific sync components
2. Authorization Providers: Handle health data permissions for each platform
3. Sync Components: Manage actual data synchronization with progress tracking
4. UI Components: Provide user interfaces for manual authorization and progress display

Components

DataSync

The main compound component that provides access to all data synchronization functionality.

Platform-specific components:

• Android Health Connect Authorization - Android permission state
• Android Health Sync - Android Health Connect data synchronization
• Apple Health Authorization - Apple permission state
• Apple Health Sync - Apple Health data synchronization

UI Components:

• ManuallyRequestSheet - Bottom sheet for manual authorization requests
• SyncProgressList - List component for displaying real-time synchronization progress

Authorization and import hooks

useHealthAuthorization() reads the authorization state from beneath either AppleHealthAuthorizationProvider or AndroidHealthConnectAuthorizationProvider. It returns the platform, current status, missing measurement types, and a request() action. The status is platform-specific; use the provider's onAuthorizationStatusChange callback when state is needed outside its subtree.

useHealthImport({ types, adapter, background? }) is a platform-neutral import hook for apps that supply their own authorization and data-reading adapter. It reports authorization by requested type and lets the host initiate import without coupling the SDK to an app's HealthKit or Health Connect policy. Both hooks are exported from @ovok/native/data-sync.

Performance & Reliability

Network Optimization

• Wi-Fi Preference: Optional sync pausing on cellular connections when wifiOnly is true
• Batch Processing: Efficient data bundling to minimize API calls
• Retry Logic: Retries network errors, HTTP 429, and HTTP 5xx saves after 1s, 4s, and 16s
• Connection Monitoring: Real-time network state awareness

Memory Management

• Chunked Processing: Large datasets processed in configurable chunks
• Instance Management: Automatic cleanup of sync service instances
• Storage Optimization: Efficient anchor-based data retrieval
• Background Processing: Non-blocking operations with progress reporting

Error Resilience

• Graceful Degradation: Partial sync completion with error isolation
• Per-type progress: A type is marked complete only after its configured records are saved
• State Recovery: Resume from last successful sync point
• Validation: Source records are mapped to the configured FHIR observation shape; the app remains responsible for domain-specific validation before submission
• User Feedback: Clear error communication and resolution guidance

Dependencies

Core Dependencies

• Apple Health: @kingstinct/react-native-healthkit for iOS health data access
• Android Health Connect: react-native-health-connect for Android health data
• FHIR Client: @ovok/core for FHIR resource management
• Network Monitoring: @react-native-community/netinfo for connectivity awareness

UI Dependencies

• Bottom Sheet: @gorhom/bottom-sheet for manual request UI
• Theme System: Uses useAppTheme for consistent styling
• Progress Components: Integration with ProgressBar module
• Safe Areas: react-native-safe-area-context for proper layout