React Native StepKit

A professional, enterprise-grade pedometer SDK for React Native.

StepKit is engineered for reliability, leveraging a true platform-native approach. Instead of forcing your application into a battery-draining foreground service for every use-case, StepKit v2 introduces a declarative Tracking Strategy Pattern allowing you to surgically choose the tracking mechanism that best fits your product requirements.

Installation

npm install react-native-stepkit

Note: This library contains custom native Android/iOS code and cannot be used with "Expo Go". You must use Expo Prebuild (EAS) or a bare React Native project.

Core Features (v2.0)

• 🔋 Battery-First Architecture: Leverages hardware-batched TYPE_STEP_COUNTER (Android) and CMPedometer (iOS) to keep the CPU asleep.
• 📦 Built-In Persistence: Step totals are aggregated and flushed to an internal native SQLite database (Android) to survive app crashes.
• 🛡️ Reboot Recovery: Catch OS boot events to gracefully recover and reset hardware baselines.
• 🧠 Declarative Tracking Modes: No more manual start() and stop(). Define your tracking intent, and the SDK handles the native infrastructure.

API Reference

1. Configuration (Required)

You must configure the SDK before querying any data. The mode dictates the internal native tracking strategy.

import StepKit from 'react-native-stepkit';

await StepKit.configure({
    mode: 'workout' // 'workout' | 'session' | 'daily_best_effort'
});

Tracking Modes Explained:

• workout: High accuracy, zero latency. Spins up a resilient Foreground Service (Android) or Background Location (iOS) to ensure zero data loss during a critical run/workout. Requires visible notifications.
• session: Accurate tracking while the user actively has the app open. Tracking dies when the app is swiped away.
• daily_best_effort: Passive 24/7 daily counting with no persistent notification. On Android this leans on the fact that TYPE_STEP_COUNTER accumulates inside the sensor hub whether or not your process exists, so the SDK never has to stay alive to keep counting. Totals are kept correct by reconciling that counter against a stored baseline - on configure(), whenever the app returns to the foreground, and from a periodic WorkManager job (see backgroundSync below).

  What survives the app being killed: the step total. Swiping the app away, Doze, and OEM battery managers do not lose steps - the hardware kept counting, and the next reconcile claims the whole delta.

  What degrades: which day those steps land on. A reconcile only knows the total for the window since the last read, so a window spanning midnight is split proportionally by elapsed time. Frequent syncs keep the window short; if the OS never runs the job and the app is not opened for days, that long window gets apportioned by time rather than by when the user actually walked.

  ⚠️ Steps taken between the last reconcile and a device reboot are genuinely unrecoverable - the counter resets to 0 and nothing recorded the tail. The SDK registers a BOOT_COMPLETED receiver to re-baseline promptly and keep the loss to that window. If you need exact attribution, use workout mode.

backgroundSync

Controls the periodic reconciliation for daily_best_effort:

await StepKit.configure({
    mode: 'daily_best_effort',
    backgroundSync: { enabled: true, intervalHours: 1 }
});

intervalHours is clamped up to 15 minutes, the shortest period Android's WorkManager honours. Disabling it does not stop steps being counted; it only widens the window that has to be attributed across day boundaries.

2. Permissions

Handles ACTIVITY_RECOGNITION (Android) and Motion & Fitness (iOS).

const status = await StepKit.checkPermission();
if (status !== 'GRANTED') {
    await StepKit.requestPermission();
}

3. Querying Steps

Fetch historical step records directly from the native SQLite database or CoreMotion.

// Get total steps for today
const todaySteps = await StepKit.getTodaySteps();
console.log(`Steps today: ${todaySteps}`);

// Query a specific date range
const history = await StepKit.getSteps({
    start: new Date('2026-08-01T00:00:00Z'),
    end: new Date('2026-08-07T23:59:59Z')
});

history.forEach(day => {
    console.log(`${day.dateString}: ${day.totalSteps} steps`);
});

4. Syncing on Foreground

sync() reads the hardware counter and folds in everything walked while the app was not running, then resolves - so the read that follows it is current. Without it, the first frame after a cold start can show the total from whenever the process was last alive.

useEffect(() => {
    const sub = AppState.addEventListener('change', state => {
        if (state === 'active') StepKit.sync().then(refresh);
    });
    return () => sub.remove();
}, []);

The SDK also reconciles on configure() and on host resume, so treat sync() as the way to await freshness rather than as something the counts depend on. Resolves false if the device has no step counter.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT