Capacitor HealthKit Plugin

:heart: Capacitor plugin to retrieve data from HealthKit :heart:

Disclaimer : for now only some of the HK data base, in the future the retrieve base will be bigger !

Getting Started

Prerequisites

• Add HealthKit to your Xcode project (section signing & capabilities)

• ADD Privacy - Health Share Usage Description to your Xcode project
• ADD Privacy - Health Update Usage Description to your Xcode project

You can simply put this into the info.plist file

	<key>NSHealthShareUsageDescription</key>
	<string>Read Health Data</string>
	<key>NSHealthUpdateUsageDescription</key>
	<string>Read Health Data</string>

Installing

Do

npm i --save @devmaxime/capacitor-healthkit

Then

npx cap update

And if you use Ionic or Angular, here a example setup:

in your .ts file add this:

import {
  ActivityData,
  CapacitorHealthkit,
  OtherData,
  QueryOutput,
  SampleNames,
  SleepData,
} from '@devmaxime/capacitor-healthkit';

const READ_PERMISSIONS = ['calories', 'stairs', 'activity', 'steps', 'distance', 'duration', 'weight'];

and then you can create async functions like this:

  public async requestAuthorization(): Promise<void> {
    try {
      await CapacitorHealthkit.requestAuthorization({
        all: [''],
        read: READ_PERMISSIONS,
        write: [''],
      });

    } catch (error) {
      console.error('[HealthKitService] Error getting Authorization:', error);
    }
  }

  private async getActivityData(
    startDate: Date,
    endDate: Date = new Date(),
  ): Promise<QueryOutput<ActivityData>> | undefined {
    try {
      const queryOptions = {
        sampleName: SampleNames.WORKOUT_TYPE,
        startDate: startDate.toISOString(),
        endDate: endDate.toISOString(),
        limit: 0,
      };

      return await CapacitorHealthkit.queryHKitSampleType<ActivityData>(queryOptions);
    } catch (error) {
      console.error(error);

      return undefined;
    }
  }

so you can use the plugin for example with the call CapacitorHealthkit.queryHKitSampleType(...

And you're all set ! :+1:

• requestAuthorization(...)
• queryHKitSampleType(...)
• isAvailable()
• multipleQueryHKitSampleType(...)
• isEditionAuthorized(...)
• multipleIsEditionAuthorized(...)
• aggregateRecords(...)
• Interfaces
• Type Aliases

requestAuthorization(...)

requestAuthorization(authOptions: AuthorizationQueryOptions) => Promise<void>

This functions will open the iOS Screen to let users choose their permissions. Keep in mind as developers, if the access has been denied by the user we will have no way of knowing - the query results will instead just be empty arrays.

| Param | Type | Description | | ----------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | authOptions | AuthorizationQueryOptions | These define which access we need. Possible Options include ['calories', 'stairs', 'activity', 'steps', 'distance', 'duration', 'weight']. |

queryHKitSampleType(...)

queryHKitSampleType<T>(queryOptions: SingleQueryOptions) => Promise<QueryOutput<T>>

This defines a query to the Healthkit for a single type of data.

When pageToken is not provided, automatic pagination is used to retrieve ALL records within the specified time range. This may take longer for large datasets but ensures complete data retrieval.

When pageToken is provided, manual pagination is used and only a single page of results is returned along with a nextPageToken for retrieving subsequent pages.

| Param | Type | Description | | ------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | queryOptions | SingleQueryOptions | defines the type of data and the timeframe which shall be queried, a limit can be set to reduce the number of results. |

Returns: Promise<QueryOutput<T>>

isAvailable()

isAvailable() => Promise<void>

This functions resolves if HealthKitData is available it uses the native HKHealthStore.isHealthDataAvailable() funtion of the HealthKit .

multipleQueryHKitSampleType(...)

multipleQueryHKitSampleType(queryOptions: MultipleQueryOptions) => Promise<any>

This defines a query to the Healthkit for multiple types of data.

When pageToken is not provided, automatic pagination is used to retrieve ALL records within the specified time range. This may take longer for large datasets but ensures complete data retrieval.

When pageToken is provided, manual pagination is used and only a single page of results is returned along with a nextPageToken for retrieving subsequent pages.

| Param | Type | Description | | ------------------ | --------------------------------------------------------------------- | ------------------------------------------------- | | queryOptions | MultipleQueryOptions | defines the sample types which can be queried for |

Returns: Promise<any>

isEditionAuthorized(...)

isEditionAuthorized(queryOptions: EditionQuery) => Promise<void>

Checks if there is writing permission for one specific sample type. This function has not been tested.

| Param | Type | Description | | ------------------ | ----------------------------------------------------- | -------------------------------------------------------------------------- | | queryOptions | EditionQuery | defines the sampletype for which you need to check for writing permission. |

multipleIsEditionAuthorized(...)

multipleIsEditionAuthorized(queryOptions: MultipleEditionQuery) => Promise<void>

Checks if there is writing permission for multiple sample types. This function has not been tested.

| Param | Type | Description | | ------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------- | | queryOptions | MultipleEditionQuery | defines the sampletypes for which you need to check for writing permission. |

aggregateRecords(...)

aggregateRecords(options: AggregateQueryOptions) => Promise<AggregateResponse>

Aggregates records of the specified type within a time range. Returns aggregated data grouped by the specified time period (e.g., daily totals). Uses HKStatisticsCollectionQuery for efficient aggregation.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | -------------------------------------------------------- | | options | AggregateQueryOptions | defines the type of data, timeframe, and grouping period |

Returns: Promise<AggregateResponse>

Interfaces

AuthorizationQueryOptions

Used for authorization of reading and writing access.

| Prop | Type | | ----------- | --------------------- | | read | string[] | | write | string[] | | all | string[] |

QueryOutput

This interface is used for any results coming from HealthKit. It always has a count and the actual results.

When using automatic pagination (no pageToken provided), all records are returned and nextPageToken will be undefined.

When using manual pagination (pageToken provided), nextPageToken will contain the token for the next page, or undefined if this is the last page.

| Prop | Type | | ------------------- | ------------------- | | countReturn | number | | resultData | T[] | | nextPageToken | string |

SingleQueryOptions

This extends the Basequeryoptions for a single sample type.

| Prop | Type | | ---------------- | ------------------- | | sampleName | string |

MultipleQueryOptions

This extends the Basequeryoptions for a multiple sample types.

| Prop | Type | | ----------------- | --------------------- | | sampleNames | string[] |

EditionQuery

This is used for checking writing permissions.

| Prop | Type | | ---------------- | ------------------- | | sampleName | string |

MultipleEditionQuery

This is used for checking writing permissions.

| Prop | Type | | ----------------- | --------------------- | | sampleNames | string[] |

AggregateResponse

Response from aggregating health records. Contains aggregated data grouped by time periods.

| Prop | Type | | ---------------- | ---------------------------- | | aggregates | AggregateData[] |

AggregateData

Aggregated data for a specific time period.

| Prop | Type | | --------------- | ------------------- | | startTime | string | | endTime | string | | value | number | | unit | string |

AggregateQueryOptions

Options for aggregating health records.

| Prop | Type | | ---------------- | ------------------------------------------------------------- | | startDate | string | | endDate | string | | sampleName | string | | groupBy | AggregateGroupBy |

Type Aliases

AggregateGroupBy

Time period for grouping aggregated data.

'hour' | 'day' | 'week' | 'month'

Initially forked from @perfood/capacitor-healthkit