Web Step Counter API 文档

web-step-counter 是一个专为移动端 Web 应用设计的高精度、防作弊步数统计组件。

安装

# 如果发布到 npm (示例)
npm install web-step-counter

或者直接引入 JS 文件：

import { WebStepCounter } from './step-counter.js';

快速开始

const counter = new WebStepCounter({
    onStep: (steps) => console.log(`步数: ${steps}`),
    onStatus: (msg, type) => console.log(`状态: ${msg}`),
});

// 必须在用户交互（点击事件）中调用
document.getElementById('btn').onclick = () => {
    counter.start();
};

配置项 (Configuration)

初始化时可传入配置对象：new WebStepCounter(config)

参数优化说明

默认参数基于市面上通用步行检测标准优化：

• 正常步行：60-120步/分钟（1-2步/秒），步间隔500-1000ms
• 快走/慢跑：120-180步/分钟（2-3步/秒），步间隔330-500ms
• 慢走场景：支持最慢0.67步/秒的步速

这些参数能够有效支持： ✅ 手机放在口袋里走路（任意姿态，包括平放） ✅ 手机拿在手里走路（竖握/平握/斜握） ✅ 室内/地下等弱GPS信号场景 ✅ 快走、慢走、正常步行等多种步速

智能姿态检测

采用姿态变化检测算法，精准区分正常走路和作弊行为：

| 场景 | 姿态特征 | 判定结果 | |------|---------|---------| | 🚶 口袋走路 | 水平放置 + 姿态持续波动 | ✅ 正常计步 | | 🤚 手持走路 | 任意角度 + 姿态持续波动 | ✅ 正常计步 | | 🎯 拍桌子作弊 | 水平放置 + 姿态几乎静止 | ❌ 静默过滤 |

核心原理：真实走路时，即使手机水平放置，由于身体晃动也会产生持续的姿态变化；而拍桌子时手机姿态几乎不变。

| 属性 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | sensitivity | Number | 12.0 | 加速度灵敏度阈值 (m/s²)。数值越小越灵敏，但也越容易误判。 | | minStepInterval | Number | 300 | 最小步频间隔 (ms)。对应最快3.3步/秒，覆盖快走和慢跑场景。 | | maxStepInterval | Number | 1500 | 最大步频间隔 (ms)。对应最慢0.67步/秒，适应慢走场景。 | | minConsecutiveSteps| Number | 4 | 连续步数门槛。连续走满 N 步才开始计入总数，防止误触。 | | cheatCheckInterval | Number | 15000 | 防作弊检查周期 (ms)。每隔15秒检查一次 GPS，减少对正常运动的干扰。 | | gpsAccuracyLimit | Number | 150 | GPS 精度要求 (米)。兼容室内、地下等弱信号场景。 | | accelerationThreshold | Number | 1.2 | 加速度变化阈值 (m/s²)。匹配正常步行的垂直加速度变化范围。 | | maxSpeed | Number | 2.8 | 最大允许速度 (m/s)。约 10km/h，超过此速度不计步。 | | orientationVarianceThreshold | Number | 3.0 | 姿态变化方差阈值。用于区分"拍桌子"和"口袋走路"，方差越小越可能是静止作弊。 | | debug | Boolean | false | 是否在控制台打印详细调试日志。 | | autoPauseOnBackground | Boolean | true | Capacitor 环境下切后台时自动暂停传感器以省电。 | | onStep | Function | null | 步数更新回调 (steps) => void | | onStatus | Function | null | 状态/作弊回调 (msg, type, code) => void | | onSensorData | Function | null | 传感器原始数据回调 (acc, orient) => void |

方法 (Methods)

start(): Promise<boolean>

初始化传感器并开始计步。

• 必须在用户点击事件中调用（iOS 权限要求）。
• 自动处理 iOS 13+ 的权限请求流程。
• 返回 true 表示启动成功，false 表示被拒绝或出错。

stop(): void

停止计步，移除所有传感器监听器，停止 GPS 轮询。

reset(): void

重置步数、防作弊历史数据和内部缓冲区。

requestOrientationPermission(): Promise<boolean>

手动请求设备方向权限的辅助方法。

• 用于解决 iOS 上某些情况下 Orientation 权限未被正确授予的问题。
• 建议在 UI 上提供一个"修复权限"按钮调用此方法。

状态与防作弊代码 (Status & Cheating Types)

onStatus(msg, type) 回调会返回当前系统的运行状态或检测到的异常。

状态类型 (type)

| 类型 (Type) | 说明 | 示例消息 | | :--- | :--- | :--- | | 'success' | 正常运行 | "正在运行", "GPS 验证正常" | | 'info' | 一般信息 | "已停止", "已重置" | | 'warning' | 警告/非阻断性问题 | "GPS 信号弱", "需手动授权 Orientation" | | 'error' | 错误/阻断性问题 | "Motion 权限被拒绝", "必须使用 HTTPS" | | 'cheating' | 检测到作弊行为 | 见下方作弊类型 |

常见作弊/异常消息

| 消息内容 | 触发原因 | 算法逻辑 | | :--- | :--- | :--- | | "检测到剧烈摇晃" | 陀螺仪检测到高频旋转 | RotationRate > 300 deg/s | | "检测到机械节奏" | 步频方差极低 (摇步机) | 最近 20 步的时间间隔标准差 < 5ms | | "检测到原地运动 (GPS)" | 步数增加但 GPS 未移动 | StepsDiff > 15 且 GPSDistance < 3m | | "速度过快 (xx km/h)" | 移动速度超过阈值 | Speed > 10 km/h (判定为骑车/开车) | | (静默丢弃) | 拍桌子作弊 | 水平放置 + 姿态方差 < 3.0 (姿态几乎静止) |

最佳实践

1. HTTPS: 必须在 HTTPS 环境下使用，否则现代浏览器拒绝访问传感器。
2. iOS 权限: 务必设计引导 UI，提示用户在弹窗中点击"允许"。
3. UI 反馈: 当 type === 'cheating' 时，建议在 UI 上显示醒目的红色警告，提示用户"步数可能无效"。
4. 姿态检测: 智能姿态检测算法已内置，无需额外配置。它能自动区分"拍桌子"和"口袋走路"，支持手机在任意姿态下正常计步。
5. 参数调优: 若在特殊场景下出现误判，可适当调整 orientationVarianceThreshold 参数（默认3.0）：
   • 增大该值（如5.0）：更严格，可能误判部分缓慢行走场景
   • 减小该值（如1.5）：更宽松，可能漏过部分拍桌子作弊