Skip to main content

AppleHealthAuthorizationProvider

A React component that handles authorization and permission management for Apple HealthKit, providing access to health data on iOS devices.

Overview​

The AppleHealthAuthorizationProvider component manages the complex flow of requesting, checking, and maintaining permissions for Apple HealthKit. It provides a declarative way to handle health data authorization and can render different UI states based on the authorization status.

Features​

  • HealthKit Integration: Seamless integration with Apple's HealthKit framework
  • Permission Management: Handles both read and write permissions for health data
  • Flexible UI States: Support for automatic requests, manual authorization UI, or fallback components
  • Status Tracking: Real-time authorization status monitoring
  • Native iOS Experience: Uses native HealthKit permission dialogs
  • Privacy Compliance: Adheres to Apple's strict health data privacy requirements

Prerequisites​

Before using this component, ensure you have the required configuration in your app.config.ts:

// app.config.ts
export default {
  ios: {
    infoPlist: {
      // Required for HealthKit access
      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
      },
    ],
  ],
};

Basic Example​

import { DataSync } from "@ovok/native/data-sync";
import { HKQuantityTypeIdentifier } from "@kingstinct/react-native-healthkit";
import React from "react";
import { ActivityIndicator, Text } from "react-native-paper";

const HealthDataComponent = () => {
  return (
    <DataSync.AppleHealthAuthorizationProvider
      readIdentifiers={[HKQuantityTypeIdentifier.bodyTemperature]}
      fallback={<ActivityIndicator />}
    >
      <Text>You are authorized to access health data</Text>
    </DataSync.AppleHealthAuthorizationProvider>
  );
};

export default HealthDataComponent;

Props​

PropTypeDefaultDescription
readIdentifiersHKQuantityTypeIdentifier[]requiredArray of HealthKit identifiers to request read access
writeIdentifiersHKQuantityTypeIdentifier[]undefinedArray of HealthKit identifiers to request write access
fallbackReact.ReactNodeundefinedComponent to render when authorization is pending
childrenReact.ReactNodeundefinedContent to render when authorization is granted
renderManualRequestUI(requestAccess: () => void) => React.ReactNode-Custom UI for manual authorization requests
skipRequestboolean-Skip automatic permission requests
onAuthorizationStatusChange(status) => voidundefinedReceives the request state and unanswered HealthKit types

Authorization States​

The provider reports these states through onAuthorizationStatusChange:

  • unknown: HealthKit has not returned a request status yet
  • shouldRequest: The permission sheet still needs to be answered
  • requesting: The permission sheet is being requested
  • ready: The request finished and children can safely start importing
  • error: The request or per-type status check failed

ready includes notRequestedReadIdentifiers and notRequestedWriteIdentifiers. These are the types HealthKit still reports as shouldRequest; the app can direct the patient to Settings for those types. HealthKit does not reveal whether a read type was denied after its request has finished, so an empty list means the request is complete, not that every read permission was granted.

skipRequest and renderManualRequestUI must be supplied together. The manual renderer receives the requestAccess callback; it is responsible for presenting the app's explanation and triggering the native request.

Behavior​

Automatic Mode (Default)​

<DataSync.AppleHealthAuthorizationProvider
  readIdentifiers={[
    HKQuantityTypeIdentifier.stepCount,
    HKQuantityTypeIdentifier.heartRate,
    HKQuantityTypeIdentifier.bodyMass,
  ]}
  writeIdentifiers={[HKQuantityTypeIdentifier.bodyMass]}
  fallback={<LoadingSpinner />}
>
  <HealthDataComponent />
</DataSync.AppleHealthAuthorizationProvider>

In automatic mode, the component:

  1. Automatically requests HealthKit permissions on mount
  2. Shows fallback UI while permissions are being processed
  3. Renders children when authorization flow is complete

Manual Authorization Mode​

<DataSync.AppleHealthAuthorizationProvider
  readIdentifiers={[
    HKQuantityTypeIdentifier.stepCount,
    HKQuantityTypeIdentifier.heartRate,
  ]}
  skipRequest={false}
  renderManualRequestUI={(requestAccess) => (
    <DataSync.ManuallyRequestSheet>
      <DataSync.ManuallyRequestSheet.Container>
        <DataSync.ManuallyRequestSheet.Title>
          Health Data Access
        </DataSync.ManuallyRequestSheet.Title>
        <DataSync.ManuallyRequestSheet.Description>
          Connect your Apple Health data for personalized health insights
        </DataSync.ManuallyRequestSheet.Description>
        <DataSync.ManuallyRequestSheet.RequestButton onPress={requestAccess}>
          Connect Apple Health
        </DataSync.ManuallyRequestSheet.RequestButton>
      </DataSync.ManuallyRequestSheet.Container>
    </DataSync.ManuallyRequestSheet>
  )}
>
  <HealthDataComponent />
</DataSync.AppleHealthAuthorizationProvider>

Platform Compatibility​

  • iOS Only: This component only works on iOS devices
  • HealthKit Availability: Requires iOS device with HealthKit support
  • iOS Version: Requires iOS 14.0+ for full functionality
  • App Store Review: Apps using HealthKit require App Store review approval

Security & Privacy​

  • Apple Privacy Standards: Complies with Apple's strict health data privacy requirements
  • User Control: Users maintain full control over what data is shared
  • No Cross-App Data: Cannot access data from other apps without user permission
  • Encryption: All data is encrypted both in transit and at rest by iOS

App Store Requirements​

When submitting apps that use HealthKit:

  1. Privacy Policy: Must include detailed health data usage description
  2. App Review: Apple manually reviews all HealthKit integrations
  3. Usage Descriptions: Must provide clear, specific usage descriptions in Info.plist
  4. Legitimate Use: Must demonstrate legitimate health-related use case

Dependencies​

  • @kingstinct/react-native-healthkit: React Native HealthKit integration
  • Apple HealthKit framework (iOS system framework)