CapHealthKit

Capacitor plugin for accessing health data from HealthKit (iOS) and Health Connect (Android).

Features

• 걸음 수 데이터 조회
• 이동 거리 데이터 조회
• 걸음 수와 거리 데이터 동시 조회
• 실시간 데이터 업데이트
• 데이터 소스 확인 및 모니터링

Installation

npm install cap-health-kit
npx cap sync

Setup

Android

1. Health Connect 앱 설치 확인
2. AndroidManifest.xml에 권한 추가:

<uses-permission android:name="android.permission.health.READ_STEPS"/>
<uses-permission android:name="android.permission.health.READ_DISTANCE"/>

iOS

1. Xcode에서 HealthKit Capability 활성화
2. Info.plist에 권한 설명 추가:

<key>NSHealthShareUsageDescription</key>
<string>걸음 수와 이동 거리 데이터를 읽기 위해 권한이 필요합니다.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>걸음 수와 이동 거리 데이터를 기록하기 위해 권한이 필요합니다.</string>

API

checkAvailability()

Health 서비스 사용 가능 여부 확인

const result = await CapHealthKit.checkAvailability();
// { available: boolean, installed: boolean }

requestAuthorization()

필요한 권한 요청

await CapHealthKit.requestAuthorization({
  read: ['steps', 'distance'],
  write: ['steps', 'distance'],
});

getStepAndDistance()

걸음 수와 거리 데이터 조회

const result = await CapHealthKit.getStepAndDistance({
  startDate: '2024-03-15T00:00:00.000Z',
  endDate: '2024-03-15T23:59:59.999Z',
});
// {
//   steps: string,
//   distance: string, // km
//   distanceMeters: string,
//   startDate: string,
//   endDate: string
// }

startStepAndDistanceUpdates()

실시간 데이터 업데이트 시작

await CapHealthKit.startStepAndDistanceUpdates({
  interval: 60000, // 밀리초 단위
});

// 이벤트 리스너
CapHealthKit.addListener('stepAndDistanceUpdate', (data) => {
  console.log(data);
});

checkDataSources()

데이터 소스 및 트래킹 앱 상태 확인

const result = await CapHealthKit.checkDataSources();
// {
//   stepSources: [{ packageName: string, appName: string, isSystemApp: boolean }],
//   distanceSources: [{ packageName: string, appName: string, isSystemApp: boolean }],
//   activeStepSources: string[],
//   activeDistanceSources: string[],
//   hasStepData: boolean,
//   hasDistanceData: boolean,
//   hasRecentStepData: boolean,
//   hasRecentDistanceData: boolean
// }

추적 앱 상태 확인 (Android 전용)

checkTrackingApps() 메서드를 사용하여 건강 데이터 추적 앱의 설치 및 활성 상태를 확인할 수 있습니다.

사용 예시

import { CapHealthKit } from '@capacitor-community/health';

const checkTrackingStatus = async () => {
  try {
    const result = await CapHealthKit.checkTrackingApps();
    console.log('설치된 추적 앱:', result.installedTrackingApps);
    console.log('추적 앱 설치 여부:', result.hasInstalledTrackingApp);
    console.log('활성 추적 앱:', result.activeTrackingApps);
    console.log('활성 추적 앱 여부:', result.hasActiveTrackingApp);
  } catch (error) {
    console.error('추적 앱 상태 확인 중 오류:', error);
  }
};

반환 데이터 형식

interface TrackingAppInfo {
  packageName: string; // 앱 패키지 이름
  appName: string; // 앱 표시 이름
  isSystemApp: boolean; // 시스템 앱 여부
}

interface TrackingAppsResult {
  installedTrackingApps: TrackingAppInfo[]; // 설치된 추적 앱 목록
  hasInstalledTrackingApp: boolean; // 추적 앱 설치 여부
  activeTrackingApps: string[]; // 활성 상태인 추적 앱 패키지 이름 목록
  hasActiveTrackingApp: boolean; // 활성 상태인 추적 앱 존재 여부
}

지원되는 추적 앱 목록

• Google Fit (com.google.android.apps.fitness)
• Samsung Health (com.samsung.android.health)
• Fitbit (com.fitbit.FitbitMobile)
• Mi Fit (com.xiaomi.hm.health)
• Huawei Health (com.huawei.health)
• Garmin Connect (com.garmin.android.apps.connectmobile)

주의사항

• 이 기능은 Android에서만 사용 가능합니다.
• 앱이 설치되어 있더라도 Health Connect와 연동되어 있지 않으면 활성 상태로 표시되지 않습니다.
• 최근 1시간 이내에 데이터를 제공한 앱만 활성 상태로 간주됩니다.
• 시스템 권한이 필요할 수 있으며, Health Connect 권한이 필요합니다.

오류 처리

try {
  const result = await CapHealthKit.checkTrackingApps();
  // 결과 처리
} catch (error) {
  if (error.message.includes('권한')) {
    // 권한 관련 오류 처리
  } else {
    // 기타 오류 처리
  }
}

모범 사례

1. 앱 시작 시 추적 앱 상태 확인

const checkInitialStatus = async () => {
  const result = await CapHealthKit.checkTrackingApps();
  if (!result.hasInstalledTrackingApp) {
    // 사용자에게 추적 앱 설치 안내
  } else if (!result.hasActiveTrackingApp) {
    // 사용자에게 추적 앱 활성화 안내
  }
};

2. 주기적인 상태 모니터링

const monitorTrackingStatus = () => {
  setInterval(async () => {
    const result = await CapHealthKit.checkTrackingApps();
    if (!result.hasActiveTrackingApp) {
      // 사용자에게 데이터 공유 설정 확인 안내
    }
  }, 3600000); // 1시간마다 확인
};

Events

• stepAndDistanceUpdate: 걸음 수와 거리 데이터 업데이트
• healthConnectError: Health Connect 관련 오류 발생

Error Handling

모든 메서드는 실패 시 오류를 throw합니다. 주요 오류 코드:

• NOT_AVAILABLE: Health 서비스 사용 불가
• NOT_AUTHORIZED: 필요한 권한 없음
• NO_DATA: 요청한 기간에 데이터 없음

Platform Specific Notes

Android

• Health Connect 앱이 설치되어 있어야 함
• 데이터는 다른 피트니스 앱에서 수집된 것을 공유받음

iOS

• HealthKit은 기본 설치되어 있음
• 기기 자체에서 걸음 수 측정 가능