Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando los siguientes comandos y sigue las instrucciones específicas para cada plataforma a continuación:

bun add @capgo/capacitor-health
bunx cap sync

Importar

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

Inicio rápido

Verifica la disponibilidad, solicita acceso de lectura para los tipos que necesites y consulta un rango de fechas.

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

Ejemplo: historial de Android de más de 30 días

Health Connect limita las lecturas históricas a menos que el usuario otorgue READ_HEALTH_DATA_HISTORY. Activa la opción con requestHistoryAccess: true y declara el permiso en tu Android manifest:

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

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

Inspeccionar historyAccessAvailable y historyAccessAuthorized según el resultado para decidir si mostrar un deep link a los ajustes.

Ejemplo: registrar una muestra de peso

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

Ejemplo: sueño con fases

Solicitud sleep en read, luego lee las muestras de un intervalo nocturno. Cuando la plataforma expone datos de fases, las muestras pueden incluir SleepStage segmentos (deep, rem, light, etc.).

Errores comunes

• La autorización es por tipo de dato: solicita cada vez que HealthDataType leas o escribas de antemano.
• Estado de instalación de Android Health Connect: usa isAvailable y openHealthConnectSettings cuando el proveedor falte o esté desactivado.
• El permiso de historial es solo para Android: se ignora en iOS, que no tiene el límite de 30 días.
• Verificar antes del prompt: usa checkAuthorization para renderizar la UI antes de llamar a requestAuthorization de nuevo.

Resumen de API

isAvailable

Indica si la plataforma actual soporta el SDK nativo de salud.

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

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

requestAuthorization

Solicita acceso de lectura/escritura a los tipos de datos proporcionados.

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

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

checkAuthorization

Verifica el estado de autorización para los tipos de datos indicados sin mostrar prompts al usuario.

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

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

readSamples

Lee muestras del tipo de dato indicado dentro del intervalo de tiempo especificado.

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

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

saveSample

Escribe una única muestra en el almacén de salud nativo.

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

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

openHealthConnectSettings

Abre la pantalla de ajustes de Health Connect (solo Android). En iOS, este método no hace nada.

Úsalo para dirigir a los usuarios a gestionar sus permisos de Health Connect o para instalar Health Connect si no está disponible.

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

await Health.openHealthConnectSettings();

showPrivacyPolicy

Muestra la política de privacidad de la app para Health Connect (solo Android). En iOS, este método no hace nada.

Muestra la misma pantalla de política de privacidad que Health Connect cuando el usuario pulsa “Privacy policy” en el diálogo de permisos.

La URL de la política de privacidad se puede configurar añadiendo un recurso de string llamado “health_connect_privacy_policy_url” en el strings.xml de tu app, o colocando un archivo HTML en www/privacypolicy.html en tus assets.

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

await Health.showPrivacyPolicy();

queryWorkouts

Consulta sesiones de entrenamiento desde el almacén de salud nativo. Compatible con iOS (HealthKit) y Android (Health Connect).

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

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

queryAggregated

Consulta datos de salud agregados desde el almacén de salud nativo. Agrupa los datos en intervalos de tiempo (hora, día, semana, mes) con operaciones como sum, average, min o max. Es más eficiente que obtener muestras individuales para rangos de fechas amplios.

Compatible con iOS (HealthKit) y Android (Health Connect).

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

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

Referencia de tipos

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

Fuente de verdad

Esta página se genera a partir del src/definitions.tsVuelve a ejecutar la sincronización cuando cambie el API público en el upstream.

Continúa desde Primeros pasos

Si estás usando Primeros pasos para planificar el dashboard y las operaciones de API, conéctalo con Usando @capgo/capacitor-health para la capacidad nativa al usar @capgo/capacitor-health, Resumen de API para el detalle de implementación en Resumen de API Overview, Introducción para el detalle de implementación en Introducción, Claves de API para el detalle de implementación en Claves de API, y Dispositivos para el detalle de implementación en Dispositivos.