Permissions

Health data requires explicit user permission before access.

Methods

HealthX.requestPermissions()

Request permissions for health data access.

const result = await HealthX.requestPermissions({
  sleep: { read: true, write: true }
});

Parameters:

interface PermissionRequest {
  sleep?: {
    read?: boolean;
    write?: boolean;
  };
}

Returns: Promise<PermissionResult>

interface PermissionResult {
  sleep?: {
    read: boolean;
    write: boolean;
  };
}

HealthX.getPermissionStatus()

Get current permission status.

const status = await HealthX.getPermissionStatus();

Returns: Promise<FullPermissionStatus>

interface FullPermissionStatus {
  sleep?: {
    read: PermissionStatus;
    write: PermissionStatus;
  };
}

type PermissionStatus = 'granted' | 'denied' | 'not_determined';

HealthX.openHealthSettings()

Open the system health app settings so users can manage permissions.

await HealthX.openHealthSettings();

Usage Example

import HealthX from 'react-native-healthx';
import { Alert, Linking } from 'react-native';

async function requestHealthPermissions() {
  // Check current status
  const currentStatus = await HealthX.getPermissionStatus();

  if (currentStatus.sleep?.read === 'granted') {
    console.log('Already have read permission');
    return true;
  }

  // Request permissions
  const result = await HealthX.requestPermissions({
    sleep: { read: true, write: true }
  });

  if (!result.sleep?.read) {
    // Permission denied - offer to open settings
    Alert.alert(
      'Permission Required',
      'Please grant health data access in settings to use this feature.',
      [
        { text: 'Cancel', style: 'cancel' },
        {
          text: 'Open Settings',
          onPress: () => HealthX.openHealthSettings()
        }
      ]
    );
    return false;
  }

  return true;
}

Platform Differences

iOS

• Permissions are requested through the standard HealthKit authorization flow
• Users can grant read-only access (write is not supported for sleep)
• Important: iOS doesn't tell you if permissions were denied, only that the request was shown
• Users manage permissions in the Health app

Android

• Uses Health Connect's runtime permission system
• Users see a system dialog with checkboxes for each permission type
• Both read and write permissions can be granted
• Users manage permissions in the Health Connect app

Permission Status

The getPermissionStatus() method returns different values:

Status	Description
granted	User has granted permission
denied	User has denied permission
not_determined	Permission hasn't been requested yet

iOS Behavior

On iOS, HealthKit doesn't provide a way to check if read permission was denied. The status may show not_determined even after the user denies access.

Best Practices

Request Only What You Need

// Good - only request read permission if you don't need write
await HealthX.requestPermissions({
  sleep: { read: true }
});

// Bad - requesting write when you don't need it
await HealthX.requestPermissions({
  sleep: { read: true, write: true }
});

Check Before Requesting

async function ensurePermissions() {
  const status = await HealthX.getPermissionStatus();

  // Only request if not already granted
  if (status.sleep?.read !== 'granted') {
    await HealthX.requestPermissions({
      sleep: { read: true }
    });
  }
}

Handle Denial Gracefully

async function getSleepWithPermission() {
  const hasPermission = await requestHealthPermissions();

  if (!hasPermission) {
    // Show UI that doesn't require health data
    return { useFallback: true };
  }

  return HealthX.sleep.getSessions({ ... });
}

Platform-Aware Write Requests

async function requestWriteIfSupported() {
  const permissions = {
    sleep: { read: true }
  };

  // Only request write on platforms that support it
  if (HealthX.supportsWrite()) {
    permissions.sleep.write = true;
  }

  return HealthX.requestPermissions(permissions);
}