Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-health
bunx cap sync

Importieren

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

Quickstart

Verfügbarkeit prüfen, Lesezugriff für die benötigten Typen anfordern und dann einen Zeitraum abfragen.

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

Beispiel: Android-Verlauf über 30 Tage hinaus

Health Connect begrenzt historische Lesezugriffe, es sei denn, der Nutzer erteilt READ_HEALTH_DATA_HISTORY. Opt-in erfolgt über requestHistoryAccess: true und deklarieren Sie die Berechtigung in Ihrem Android-Manifest:

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

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

Prüfe historyAccessAvailable und historyAccessAuthorized am Ergebnis, um zu entscheiden, ob ein Settings-Deep-Link angezeigt wird.

Beispiel: Gewichtswert loggen

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

Beispiel: Schlaf mit Phasen

Anfrage sleep in einem read, dann Samples für ein nächtliches Zeitfenster lesen. Wenn die Plattform Phasendaten bereitstellt, können die Samples SleepStage Segmente (deep, rem, light, usw.).

Häufige Stolperfallen

• Autorisierung erfolgt pro Datentyp: Fordere jeden HealthDataType vorab an, den du liest oder schreibst.
• Installationsstatus von Android Health Connect: Verwende isAvailable und openHealthConnectSettings , wenn der Anbieter fehlt oder deaktiviert ist.
• History-Berechtigung nur für Android: Wird auf iOS ignoriert, da dort die 30-Tage-Grenze nicht gilt.
• Prüfen vor dem Prompt: verwenden checkAuthorization um die UI vor dem Aufruf zu rendern requestAuthorization erneut aus.

API Übersicht

isAvailable

Gibt zurück, ob die aktuelle Plattform das native Health-SDK unterstützt.

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

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

requestAuthorization

Fordert Lese-/Schreibzugriff auf die angegebenen Datentypen an.

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

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

checkAuthorization

Prüft den Autorisierungsstatus für die angegebenen Datentypen, ohne den Nutzer zu fragen.

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

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

readSamples

Liest Samples für den angegebenen Datentyp innerhalb des festgelegten Zeitraums aus.

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

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

saveSample

Schreibt ein einzelnes Sample in den nativen Health Store.

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

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

openHealthConnectSettings

Öffnet die Health-Connect-Einstellungen (nur Android). Unter iOS bewirkt diese Methode nichts.

Nutze dies, um Nutzer ihre Health-Connect-Berechtigungen verwalten zu lassen oder Health Connect zu installieren, falls es nicht verfügbar ist.

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

await Health.openHealthConnectSettings();

showPrivacyPolicy

Zeigt die Datenschutzerklärung der App für Health Connect an (nur Android). Auf iOS tut diese Methode nichts.

Dies zeigt dieselbe Datenschutzrichtungs-Ansicht, die Health Connect anzeigt, wenn der Benutzer im Berechtigungsdialog auf „Datenschutzrichtlinie“ tippt.

Die URL der Datenschutzerklärung kann konfiguriert werden, indem eine Zeichenkettenressource mit dem Namen „health_connect_privacy_policy_url“ in der strings.xml Ihrer App hinzugefügt wird, oder indem eine HTML-Datei unter www/privacypolicy.html in Ihren Assets abgelegt wird.

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

await Health.showPrivacyPolicy();

queryWorkouts

Abfragt Trainingssitzungen aus dem nativen Health Store. Unterstützt auf iOS (HealthKit) und Android (Health Connect).

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

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

queryAggregated

Abfragt aggregierte Gesundheitsdaten aus dem nativen Health Store. Aggregiert Daten in Zeitintervallen (Stunde, Tag, Woche, Monat) mit Operationen wie Summe, Durchschnitt, Minimum oder Maximum. Dies ist effizienter als das Abrufen einzelner Samples für große Datumsbereiche.

Unterstützt auf iOS (HealthKit) und Android (Health Connect).

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

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

Typreferenz

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

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Dashboard- und API-Operationen zu planen, verbinde es mit @capgo/capacitor-health verwenden für die native Funktion in „@capgo/capacitor-health verwenden“, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.