@capgo/capacitor-pedometer

Count steps in your Capacitor app with the device motion sensors: live step updates and history queries for fitness, health and challenge apps.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-pedometer in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-pedometer to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Live updates: startMeasurementUpdates() streams the measurement event, stopMeasurementUpdates() ends it.
• History on iOS: getMeasurement() returns steps for a time range.
• Rich data on iOS: distance, pace, cadence and floors ascended or descended from Core Motion.
• Availability: isAvailable() tells you which metrics the device supports.
• Permissions: motion permission on iOS and ACTIVITY_RECOGNITION on Android.
• Platforms: iOS and Android. Android counts steps with the step sensor. Not available on web.

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

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

Then use the following prompt:

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

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-pedometer
npx cap sync

Configuration

iOS

Add the following to your Info.plist:

<key>NSMotionUsageDescription</key>
<string>We need access to your motion data to track steps and activity</string>

Android

The plugin will automatically add the ACTIVITY_RECOGNITION permission to your AndroidManifest.xml.

For Android 10 (API 29) and above, you need to request the ACTIVITY_RECOGNITION permission at runtime.

API

• getMeasurement(...)
• isAvailable()
• startMeasurementUpdates()
• stopMeasurementUpdates()
• checkPermissions()
• requestPermissions()
• addListener('measurement', ...)
• removeAllListeners()
• getPluginVersion()
• Interfaces
• Type Aliases

getMeasurement(...)

getMeasurement(options?: GetMeasurementOptions | undefined) => Promise<Measurement>

Get pedometer measurements for a specified time range.

Returns: Promise<Measurement>

Since: 0.0.1

isAvailable()

isAvailable() => Promise<IsAvailableResult>

Check which pedometer features are available on this device.

Returns: Promise<IsAvailableResult>

Since: 0.0.1

startMeasurementUpdates()

startMeasurementUpdates() => Promise<void>

Start receiving real-time pedometer measurement updates.

On Android and iOS, the measurement event is only fired after calling startMeasurementUpdates().

Since: 0.0.1

stopMeasurementUpdates()

stopMeasurementUpdates() => Promise<void>

Stop receiving real-time pedometer measurement updates.

Since: 0.0.1

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check permission to access pedometer data.

On Android, this checks the ACTIVITY_RECOGNITION permission. On iOS, this checks the motion usage permission.

Returns: Promise<PermissionStatus>

Since: 0.0.1

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission to access pedometer data.

On Android, this requests the ACTIVITY_RECOGNITION permission. On iOS, this requests motion usage permission.

Returns: Promise<PermissionStatus>

Since: 0.0.1

addListener('measurement', ...)

addListener(eventName: 'measurement', listenerFunc: (event: MeasurementEvent) => void) => Promise<PluginListenerHandle>

Called when a new pedometer measurement is received.

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.0.1

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

Measurement

GetMeasurementOptions

IsAvailableResult

PermissionStatus

PluginListenerHandle

Type Aliases

MeasurementEvent

Measurement

Usage

import { CapacitorPedometer } from '@capgo/capacitor-pedometer';

// Check availability
const availability = await CapacitorPedometer.isAvailable();
console.log('Features available:', availability);

// Check and request permissions
const permission = await CapacitorPedometer.checkPermissions();
if (permission.activityRecognition !== 'granted') {
  await CapacitorPedometer.requestPermissions();
}

// Start real-time updates
await CapacitorPedometer.addListener('measurement', (data) => {
  console.log('Steps:', data.numberOfSteps);
  console.log('Distance:', data.distance);
});

await CapacitorPedometer.startMeasurementUpdates();

// Query historical data (iOS only - requires start and end timestamps)
const now = Date.now();
const yesterday = now - (24 * 60 * 60 * 1000);
const measurement = await CapacitorPedometer.getMeasurement({
  start: yesterday,
  end: now
});

// Stop updates
await CapacitorPedometer.stopMeasurementUpdates();
await CapacitorPedometer.removeAllListeners();

Platform Support

Notes

• On Android, only step counting is available. The plugin uses the TYPE_STEP_COUNTER sensor.
• On iOS, all features are available on supported devices using CMPedometer.
• Historical data queries require explicit start and end timestamps on iOS.
• Android's step counter gives cumulative steps since last device reboot; the plugin tracks the delta.
• Measurements are paused when the app is in the background.

License

MIT