capacitor-pedometer

A plugin to make building fitness apps just that easier, using Android Health Connect and Sensor Manager on Android and Apple HealthKit on IOS.

Install

npm install capacitor-pedometer
npx cap sync

Setup

iOS

• Before you can use HealthKit, you must enable the HealthKit capabilities for your app. See https://developer.apple.com/documentation/healthkit/setting-up-healthkit
• Make sure you have the following keys in your Info.plist file:

<key>NSHealthShareUsageDescription</key>
<string> -Your reason for using HealthKit- </string>
<key>NSHealthUpdateUsageDescription</key>
<string> -Your reason for using HealthKit- </string>

Android

• Add these in the application tag of your AndroidManifest.xml

<!-- For supported versions through Android 13, create an activity to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
        <activity
            android:name="com.hamjad.capacitor.pedometer.PermissionsRationaleActivity"
            android:exported="true">
          <intent-filter>
            <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
          </intent-filter>
        </activity>

        <!-- For versions starting Android 14, create an activity alias to show the rationale
            of Health Connect permissions once users click the privacy policy link. -->
        <activity-alias
            android:name="ViewPermissionUsageActivity"
            android:exported="true"
            android:targetActivity="com.hamjad.capacitor.pedometer.PermissionsRationaleActivity"
            android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
          <intent-filter>
            <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
            <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
          </intent-filter>
        </activity-alias>

• Declare the Health Connect package name in your AndroidManifest.xml after the application tag.

  <!-- Check if Health Connect is installed -->
    <queries>
        <package android:name="com.google.android.apps.healthdata" />
    </queries>

• Lastly, Add the permissions for the required data types such as;

<uses-permission android:name="android.permission.health.READ_STEPS" />
<uses-permission android:name="android.permission.health.READ_DISTANCE" />
<uses-permission android:name="android.permission.health.READ_TOTAL_CALORIES_BURNED" />

• Note that this plugin was built using gradle plugin verion com.android.tools.build:gradle:8.7.2 which requires gradle version 8.9

Android Step Sensor

Because Health Connect acts more as central store for health and fitness data rather than a pedometer that tracks steps, This function was created for that exact purpose in mind. It combines Android's internal step Sensor with Google's Recording API which allows retrieving step count data from a mobile device in a battery-efficient way, which the function then stores in Health Connect.

Set up Step Sensor

• Add this in the application tag of your AndroidManifest.xml

   <activity
      android:name="com.hamjad.capacitor.pedometer.StepSensor"
      android:exported="true"
      android:theme="@android:style/Theme.Translucent.NoTitleBar">
      <intent-filter>
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.DEFAULT" />
      </intent-filter>
    </activity>

• Add permissions to use Android Sensor and write Steps data to Health Connect;

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

API

• checkAvailability()
• requestPermission()
• checkPermission()
• useStepSensor()
• queryActivity(...)
• queryAggregatedActivity(...)
• getChangesToken(...)
• getChanges(...)
• Interfaces
• Type Aliases

checkAvailability()

checkAvailability() => Promise<AvailabilityResult>

Checks if Android Health Connect or Apple HealthKit is available. If available will return AVAILABLE, otherwise it will return UNAVAILABLE or NOTINSTALLED.

Returns: Promise<AvailabilityResult>

requestPermission()

requestPermission() => Promise<PermissionResponse>

Requests permissions for steps, distance and calories

Returns: Promise<PermissionResponse>

checkPermission()

checkPermission() => Promise<PermissionResponse>

Check permissions that have been previously requested.

Returns: Promise<PermissionResponse>

useStepSensor()

useStepSensor() => Promise<SensorResponse>

Use Android's Sensor API to manually count, record and store steps in Health Connect. Requires ACTIVITY_RECOGNITION permission. Only available on Android.

Returns: Promise<SensorResponse>

queryActivity(...)

queryActivity(requestOptions: QueryActivityRequest) => Promise<QueryActivityResponse>

Query activity data

| Param | Type | | -------------------- | --------------------------------------------------------------------- | | requestOptions | QueryActivityRequest |

Returns: Promise<QueryActivityResponse>

queryAggregatedActivity(...)

queryAggregatedActivity(requestOptions: QueryAggregatedActivityRequest) => Promise<QueryAggregatedActivityResponse>

Query aggregated activity data

| Param | Type | | -------------------- | ----------------------------------------------------------------------------------------- | | requestOptions | QueryAggregatedActivityRequest |

Returns: Promise<QueryAggregatedActivityResponse>

getChangesToken(...)

getChangesToken(activityType: Activity[]) => Promise<ChangesTokenResult>

Android only Get changes token to watch for changes in Health Connect. Even though you can get a token for multiple activity types. Android recommends getting separate tokens per activity type instead of getting them in bulk to avoid having an Exception in case one of the permissions is revoked.

| Param | Type | | ------------------ | ----------------------- | | activityType | Activity[] |

Returns: Promise<ChangesTokenResult>

getChanges(...)

getChanges(token: string) => Promise<ChangesResult>

Android only Get Health Connect changes

| Param | Type | | ----------- | ------------------- | | token | string |

Returns: Promise<ChangesResult>

Interfaces

PermissionResponse

| Prop | Type | | ----------------- | --------------------------------------------------------------------------- | | allGranted | boolean | | permissions | mappedPermissionRecords |

SensorResponse

| Prop | Type | | ------------ | ---------------- | | result | any |

QueryActivityResponse

| Prop | Type | | ---------------- | ---------------------------- | | activities | QueryActivity[] | | pageToken | string |

QueryActivityRequest

| Prop | Type | Description | Default | | ---------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | startDate | string | | | | endDate | string | | | | activityType | Activity | | | | filterType | Filter | If between is choose then startDate and endDate are required. If after is choose then startDate is required. If before is choose then endDate is required. | "between" | | dataOriginFilter | string[] | Only used on Android. | | | limit | number | | | | ascending | boolean | | | | pageToken | string | Only used on Android. | |

QueryAggregatedActivityResponse

| Prop | Type | | -------------------- | ------------------------------- | | aggregatedData | AggregatedSample[] |

AggregatedSample

| Prop | Type | | ----------------- | --------------------- | | startDate | string | | endDate | string | | value | number | | dataOrigins | string[] |

QueryAggregatedActivityRequest

| Prop | Type | | ------------------ | --------------------------------------------- | | startDate | string | | endDate | string | | activityType | Activity | | bucket | Bucket |

ChangesTokenResult

| Prop | Type | | ----------- | ------------------- | | token | string |

ChangesResult

| Prop | Type | | --------------- | ---------------------- | | changes | Changes[] | | nextToken | string |

Changes

| Prop | Type | | ------------ | --------------------------------- | | type | 'upsert' | 'delete' | | record | QueryActivity[] |

Type Aliases

AvailabilityResult

{ result: 'AVAILABLE' | 'UNAVAILABLE' | 'NOTINSTALLED'; }

mappedPermissionRecords

{ [PermissionRecordKey in 'readSteps' | 'writeSteps' | 'distance' | 'calories']: boolean; }

QueryActivity

{ id: string; startDate: string; endDate: string; value: number; dataOrigin?: string; sourceDevice?: Device; }

Device

'UNKNOWN' | 'WATCH' | 'PHONE' | 'SCALE' | 'RING' | 'HEAD_MOUNTED' | 'FITNESS_BAND' | 'CHEST_STRAP' | 'SMART_DISPLAY'

Activity

'steps' | 'distance' | 'calories'

Filter

'between' | 'after' | 'before'

Bucket

'hour' | 'day' | 'weeks' | 'month'