Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda menggunakan perintah berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih suka Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti instruksi khusus platform di bawah ini:

bun add @capgo/capacitor-health
bunx cap sync

Impor

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

Mulai cepat

Cek ketersediaan, minta akses baca untuk tipe yang dibutuhkan, lalu query rentang tanggal.

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

async function loadTodaysSteps() {
  const { available, reason } = await Health.isAvailable();
  if (!available) {
    console.warn('Health data not available', reason);
    return;
  }

  await Health.requestAuthorization({
    read: ['steps', 'heartRate'],
    write: ['weight'],
  });

  const today = await Health.readSamples({
    dataType: 'steps',
    startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
    endDate: new Date().toISOString(),
    limit: 500,
  });

  return today;
}

Contoh: riwayat Android lebih dari 30 hari

Health Connect membatasi pembacaan riwayat kecuali pengguna memberikan READ_HEALTH_DATA_HISTORY. Opt in dengan requestHistoryAccess: true dan deklarasikan permission di Android manifest Anda:

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

await Health.requestAuthorization({
  read: ['steps'],
  requestHistoryAccess: true,
});

Inspeksi historyAccessAvailable dan historyAccessAuthorized pada hasilnya untuk menentukan apakah akan menampilkan deep link pengaturan.

Contoh: mencatat sample berat badan

await Health.saveSample({
  dataType: 'weight',
  value: 72.4,
  unit: 'kilogram',
  startDate: new Date().toISOString(),
  endDate: new Date().toISOString(),
});

Contoh: tidur dengan tahapan

Permintaan sleep di read, lalu baca sampel untuk rentang waktu satu malam. Saat platform menyediakan data tahapan, sampel dapat mencakup SleepStage segmen (deep, rem, light, dll.).

Masalah umum

• Otorisasi dilakukan per tipe data: minta setiap kali HealthDataType Anda baca atau tulis di awal.
• Status instalasi Android Health Connect: gunakan isAvailable dan openHealthConnectSettings saat provider hilang atau dinonaktifkan.
• Izin History hanya untuk Android: diabaikan di iOS, yang tidak pakai batas 30 hari.
• Cek sebelum prompt: gunakan checkAuthorization untuk merender UI sebelum memanggil requestAuthorization lagi.

Ikhtisar API

isAvailable

Mengembalikan status apakah platform saat ini mendukung native health SDK.

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

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

requestAuthorization

Meminta akses baca/tulis ke tipe data yang disediakan.

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

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

checkAuthorization

Memeriksa status otorisasi untuk tipe data yang diberikan tanpa memunculkan prompt ke user.

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

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

readSamples

Membaca sampel untuk tipe data tertentu dalam rentang waktu yang ditentukan.

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

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

saveSample

Menulis satu sampel ke native health store.

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

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

openHealthConnectSettings

Membuka layar pengaturan Health Connect (khusus Android). Di iOS, method ini tidak melakukan apa pun.

Gunakan ini untuk mengarahkan user mengelola izin Health Connect atau menginstal Health Connect jika belum tersedia.

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

await Health.openHealthConnectSettings();

showPrivacyPolicy

Menampilkan kebijakan privasi aplikasi untuk Health Connect (hanya Android). Di iOS, metode ini tidak melakukan apa pun.

Ini menampilkan layar kebijakan privasi yang sama dengan yang ditampilkan Health Connect saat pengguna mengetuk “Privacy policy” pada dialog izin.

URL kebijakan privasi dapat dikonfigurasi dengan menambahkan resource string bernama “health_connect_privacy_policy_url” di strings.xml aplikasi Anda, atau dengan menempatkan file HTML di www/privacypolicy.html dalam assets Anda.

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

await Health.showPrivacyPolicy();

queryWorkouts

Melakukan query sesi workout dari native health store. Didukung di iOS (HealthKit) dan Android (Health Connect).

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

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

queryAggregated

Melakukan query data kesehatan teragregasi dari native health store. Mengagregasi data ke dalam bucket waktu (jam, hari, minggu, bulan) dengan operasi seperti sum, average, min, atau max. Ini lebih efisien daripada mengambil sampel individual untuk rentang tanggal yang besar.

Didukung di iOS (HealthKit) dan Android (Health Connect).

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

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

Referensi Tipe

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[];
  /**
   * Android only: request access to health data older than 30 days.
   * Requires `android.permission.health.READ_HEALTH_DATA_HISTORY` in the manifest.
   */
  requestHistoryAccess?: boolean;
}

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;
}

Sumber Kebenaran

Halaman ini dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan operasi dashboard dan API, hubungkan dengan Menggunakan @capgo/capacitor-health untuk kapabilitas native saat menggunakan @capgo/capacitor-health, Ikhtisar API untuk detail implementasi di Ringkasan API, Pendahuluan untuk detail implementasi di Pendahuluan, Kunci API untuk detail implementasi di API Keys, dan Perangkat untuk detail implementasi di Perangkat.