Erste Schritte

Installieren

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

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

Nutze anschließend 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 bevorziehst, 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 älter als 30 Tage

Health Connect begrenzt historische Lesezugriffe, sofern der Nutzer nicht READ_HEALTH_DATA_HISTORY. Opt-in mit requestHistoryAccess: true und deklariere die Berechtigung in deinem 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 basierend auf dem Ergebnis, ob ein Deep Link zu den Einstellungen angezeigt werden soll.

Beispiel: Ein Gewichts-Sample loggen

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

Beispiel: Schlaf mit Phasen

Fordern Sie sleep in read, dann Proben für ein nächtliches Zeitfenster lesen. Sobald die Plattform Phasen-Daten bereitstellt, können die Proben enthalten: SleepStage Segmente (deep, rem, light, etc.).

Häufige Fehlerquellen

• Die Autorisierung erfolgt pro Datentyp: fordere jede HealthDataType Lese- oder Schreiboperation vorab an.
• Android Health Connect Installationsstatus: verwende isAvailable und openHealthConnectSettings , wenn der Provider fehlt oder deaktiviert ist.
• History-Berechtigung ist nur für Android: wird auf iOS ignoriert, da dort die 30-Tage-Grenze nicht gilt.
• Vor dem Prompt prüfen: verwenden checkAuthorization um die UI vor dem Aufruf von requestAuthorization again.

API Übersicht

isAvailable

Gibt an, 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). Auf iOS bewirkt diese Methode nichts.

Nutze dies, damit Nutzer ihre Health-Connect-Berechtigungen verwalten oder Health Connect installieren können, 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 (nur Android). Unter iOS bewirkt diese Methode nichts.

Dies zeigt denselben Datenschutzbildschirm an, den Health Connect anzeigt, wenn der Nutzer im Berechtigungsdialog auf „Datenschutzrichtlinie“ tippt.

Die URL der Datenschutzerklärung kann über eine String-Resource namens „health_connect_privacy_policy_url“ in deiner strings.xml konfiguriert werden, oder indem du eine HTML-Datei unter www/privacypolicy.html in deinen Assets ablegst.

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

await Health.showPrivacyPolicy();

queryWorkouts

Fragt Workout-Sessions aus dem nativen Health Store ab. 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

Fragt aggregierte Gesundheitsdaten aus dem nativen Health Store ab. Daten werden in Zeitintervalle (Stunde, Tag, Woche, Monat) gruppiert, mit Operationen wie Summe, Durchschnitt, Min oder Max. Dies ist effizienter als das Abrufen einzelner Samples über große Zeiträume.

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

Typ-Referenz

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- src/definitions.ts. Führe den Sync erneut aus, wenn sich der öffentliche API upstream ändert.

Weiter mit Getting Started

Wenn Sie ... verwenden Erste Schritte Um Dashboard- und API-Operationen zu planen, verbinde es mit @capgo/capacitor-health verwenden für die native Funktionalität bei der Nutzung von @capgo/capacitor-health, API Übersicht für Details zur Implementierung in der Übersicht zu API, Einführung für das Implementierungsdetail in der Einleitung, API Keys für die Implementierungsdetails in den API Keys und Geräte für die Implementierungsdetails bei Devices.