시작 가이드

설치

AI-Assisted Setup을 사용하여 플러그인을 설치할 수 있습니다. AI 도구에 다음 명령어를 사용하여 Capgo 기능을 추가하세요.

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

다음 명령어를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-health` plugin in my project.

만약 Manual Setup을 선호한다면, 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/capacitor-health
bunx cap sync

import

import { Health } from '@capgo/capacitor-health';

API 개요

isAvailable

현재 플랫폼이 네이티브 헬스 SDK를 지원하는지 여부를 반환합니다.

import { Health } from '@capgo/capacitor-health';

const result = await Health.isAvailable();
console.log(result);

requestAuthorization

제목: 권한 요청

import { Health } from '@capgo/capacitor-health';

const result = await Health.requestAuthorization({ read: ['steps'] });
console.log(result);

checkAuthorization

제목: 권한 확인

import { Health } from '@capgo/capacitor-health';

const result = await Health.checkAuthorization({ read: ['steps'] });
console.log(result);

readSamples

지정된 데이터 유형의 샘플을 지정된 시간 범위 내에서 읽습니다.

import { Health } from '@capgo/capacitor-health';

const result = await Health.readSamples({ dataType: 'steps' });
console.log(result);

saveSample

자연스러운 보건 저장소에 단일 샘플을 씁니다.

import { Health } from '@capgo/capacitor-health';

await Health.saveSample({
  dataType: 'steps',
  value: 1,
});

openHealthConnectSettings

Android에서만 보건 연결 설정 화면을 엽니다. iOS에서는 이 메서드는 아무런 동작도 하지 않습니다.

사용자에게 보건 연결 권한을 관리하거나 설치하도록 안내하세요. (iOS에서만)

import { Health } from '@capgo/capacitor-health';

await Health.openHealthConnectSettings();

showPrivacyPolicy

Android에서만 앱의 보건 연결 개인 정보 보호 정책을 표시합니다. iOS에서는 이 메서드는 아무런 동작도 하지 않습니다.

사용자가 권한 대화 상자에서 ‘개인 정보 보호 정책’을 탭했을 때 보건 연결이 표시하는 동일한 개인 정보 보호 정책 화면을 표시합니다.

privasy policy URL을 설정하려면 앱의 strings.xml에 “health_connect_privacy_policy_url”라는 이름의 문자열 리소스를 추가하거나 www/privacypolicy.html 파일을 앱의 assets에 위치시키면 됩니다.

import { Health } from '@capgo/capacitor-health';

await Health.showPrivacyPolicy();

queryWorkouts

native 헬스 스토어에서 운동 세션을 조회합니다. iOS (HealthKit)와 Android (Health Connect)에서 지원됩니다.

import { Health } from '@capgo/capacitor-health';

const result = await Health.queryWorkouts({ workoutType: 'americanFootball' });
console.log(result);

queryAggregated

native 헬스 스토어에서-aggregated 헬스 데이터를 조회합니다. 시간 단위로 데이터를 집계 (시간, 일, 주, 월) 하며 합, 평균, 최소, 최대와 같은 연산을 수행합니다. 대량의 날짜 범위에 대한 개별 샘플을 가져오기보다 효율적입니다.

iOS (HealthKit)와 Android (Health Connect)에서 지원됩니다.

import { Health } from '@capgo/capacitor-health';

const result = await Health.queryAggregated({ dataType: 'steps' });
console.log(result);

타입 참조

AvailabilityResult

export interface AvailabilityResult {
  available: boolean;
  /** Platform specific details (for debugging/diagnostics). */
  platform?: 'ios' | 'android' | 'web';
  reason?: string;
}

AuthorizationOptions

export interface AuthorizationOptions {
  /** Data types that should be readable after authorization. */
  read?: HealthDataType[];
  /** Data types that should be writable after authorization. */
  write?: HealthDataType[];
}

AuthorizationStatus

export interface AuthorizationStatus {
  readAuthorized: HealthDataType[];
  readDenied: HealthDataType[];
  writeAuthorized: HealthDataType[];
  writeDenied: HealthDataType[];
}

QueryOptions

export interface QueryOptions {
  /** The type of data to retrieve from the health store. */
  dataType: HealthDataType;
  /** Inclusive ISO 8601 start date (defaults to now - 1 day). */
  startDate?: string;
  /** Exclusive ISO 8601 end date (defaults to now). */
  endDate?: string;
  /** Maximum number of samples to return (defaults to 100). */
  limit?: number;
  /** Return results sorted ascending by start date (defaults to false). */
  ascending?: boolean;
}

ReadSamplesResult

export interface ReadSamplesResult {
  samples: HealthSample[];
}

WriteSampleOptions

export interface WriteSampleOptions {
  dataType: HealthDataType;
  value: number;
  /**
   * Optional unit override. If omitted, the default unit for the data type is used
   * (count for `steps`, meter for `distance`, kilocalorie for `calories`, bpm for `heartRate`, kilogram for `weight`).
   */
  unit?: HealthUnit;
  /** ISO 8601 start date for the sample. Defaults to now. */
  startDate?: string;
  /** ISO 8601 end date for the sample. Defaults to startDate. */
  endDate?: string;
  /** Metadata key-value pairs forwarded to the native APIs where supported. */
  metadata?: Record<string, string>;
  /** For blood pressure data, the systolic value in mmHg. Required when dataType is 'bloodPressure'. */
  systolic?: number;
  /** For blood pressure data, the diastolic value in mmHg. Required when dataType is 'bloodPressure'. */
  diastolic?: number;
}

QueryWorkoutsOptions

export interface QueryWorkoutsOptions {
  /** Optional workout type filter. If omitted, all workout types are returned. */
  workoutType?: WorkoutType;
  /** Inclusive ISO 8601 start date (defaults to now - 1 day). */
  startDate?: string;
  /** Exclusive ISO 8601 end date (defaults to now). */
  endDate?: string;
  /** Maximum number of workouts to return (defaults to 100). */
  limit?: number;
  /** Return results sorted ascending by start date (defaults to false). */
  ascending?: boolean;
  /**
   * Anchor for pagination. Use the anchor returned from a previous query to continue from that point.
   * On iOS, this is the ISO 8601 cursor returned by the previous query. On Android, this uses
   * Health Connect's pageToken.
   * Omit this parameter to start from the beginning.
   */
  anchor?: string;
}

QueryWorkoutsResult

export interface QueryWorkoutsResult {
  workouts: Workout[];
  /**
   * Anchor for the next page of results. Pass this value as the anchor parameter in the next query
   * to continue pagination. If undefined or null, there are no more results.
   */
  anchor?: string;
}

QueryAggregatedOptions

export interface QueryAggregatedOptions {
  /** The type of data to aggregate from the health store. */
  dataType: HealthDataType;
  /** Inclusive ISO 8601 start date (defaults to now - 1 day). */
  startDate?: string;
  /** Exclusive ISO 8601 end date (defaults to now). */
  endDate?: string;
  /** Time bucket for aggregation (defaults to 'day'). */
  bucket?: BucketType;
  /** Aggregation operation to perform (defaults to 'sum'). */
  aggregation?: AggregationType;
}

QueryAggregatedResult

export interface QueryAggregatedResult {
  samples: AggregatedSample[];
}

HealthDataType

export type HealthDataType =
  | 'steps'
  | 'distance'
  | 'calories'
  | 'heartRate'
  | 'weight'
  | 'sleep'
  | 'respiratoryRate'
  | 'oxygenSaturation'
  | 'restingHeartRate'
  | 'heartRateVariability'
  | 'bloodPressure'
  | 'bloodGlucose'
  | 'bodyTemperature'
  | 'height'
  | 'flightsClimbed'
  | 'exerciseTime'
  | 'distanceCycling'
  | 'bodyFat'
  | 'basalBodyTemperature'
  | 'basalCalories'
  | 'totalCalories'
  | 'mindfulness'
  | 'workouts';

HealthSample

export interface HealthSample {
  dataType: HealthDataType;
  value: number;
  unit: HealthUnit;
  startDate: string;
  endDate: string;
  sourceName?: string;
  sourceId?: string;
  /** Platform-specific unique identifier (HealthKit UUID on iOS, Health Connect metadata ID on Android). */
  platformId?: string;
  /** For sleep data, indicates the sleep state (e.g., 'asleep', 'awake', 'rem', 'deep', 'light'). */
  sleepState?: SleepState;
  /** For blood pressure data, the systolic value in mmHg. */
  systolic?: number;
  /** For blood pressure data, the diastolic value in mmHg. */
  diastolic?: number;
}

실질적 출처

이 페이지는 플러그인의 src/definitions.ts Re-run the sync when the public API changes upstream.

Getting Started에서 계속

이러한 기능을 사용 중이라면 시작하기 계획 대시보드 및 API 운영을 위해 연결하세요. @capgo/capacitor-체크 상태 Using @capgo/capacitor-health API 개요 API Overview 소개 소개에 대한 구현 세부 정보를 위해 API 키 API 키에 대한 구현 세부 정보를 위해, 장치 소개에 대한 구현 세부 정보를 위해