更新记录
1.4.0(2026-10-13)
- 新增 三端「后台常驻持续定位上报」:App 退到后台 / 锁屏 / 前端 JS 被回收后,原生继续按间隔采集定位并上传到你的服务器(详见 readme「后台常驻持续定位上报专栏」)
- 新 API:
startBackgroundLocationUploadAsync/stopBackgroundLocationUpload/getBackgroundLocationUploadStatus/getBackgroundLocationUploadRecordsAsync/onBackgroundLocationUploadEvent/offBackgroundLocationUploadEvent - 本地离线队列(断网缓存、失败重试、失败区),批量上传与单点实时两种模式
- 一键授权(位置开关 / 前台 / 后台始终 / 通知),健康体检
healthIssues - 拉活自动恢复:配置原生持久化,被杀后经保活拉活 / 开机 / 重启 App 自动恢复上报,无需前端调用
- 全局事件监听:页面重新打开即可继续收到点位 / 上传结果 / 状态
- 坐标系 wgs84 / gcj02 / bd09
- 新 API:
- 重要 鸿蒙宿主必须在
harmony-configs/entry/src/main/module.json5中为 EntryAbility 声明"backgroundModes": ["location"],否则后台无法常驻(详见 readme 专栏「鸿蒙宿主必配」) - 修复 iOS:通知代理不再抢占宿主、BGTask 正确完成、音频中断自动恢复、JSON 拼接、死代码清理;冷启动由启动钩子自动恢复
- 修复 鸿蒙:长时任务、@kit 迁移、持久化、权限真实判断、Ability 名等;旧 API 行为变化见 readme「鸿蒙行为变化」
- 优化 Android:定位双 provider 择优、监听移到后台线程、逆地理节流、去除主线程 sleep
- 说明 修改后需重新制作自定义调试基座或云打包才生效
1.3.8(2026-08-19)
-ios 长时间活动失效后自动弹出通知提示
- 新增 iOS:
restoreIOSActivities(onLocation?)冷启动一键恢复 + 重挂定位回调(自动重注册 → 重挂回调 → 确保音频播放),返回IOSKeepAliveState状态快照 - 新增 iOS:
getIOSKeepAliveState()只读状态查询(running / locationActive / musicActive / locationInterval,locationActive为「运行时 OR 持久化意图」) - 增强 iOS:
register()注册前读取was_running,若上次被杀前在运行 → 从 UserDefaults 自动恢复定位/音频(自愈守卫,已在运行时不重复启动);中断通知自定义文案(enableInterruptNotification / delay / title / body)持久化,恢复时读回 - 增强 iOS:
restoreKeepAlive()改用持久化中断 4 参数重register()(register 内部自动恢复定位/音频)
1.3.7(2026-08-13)
-优化ios新版本环节内联吊用
查看更多平台兼容性
uni-app(4.18)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| √ | √ | × | × | √ | - | 5.0 | 12 | √ |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | × | × | × | × |
uni-app x(4.18)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | 5.0 | 12 | √ | - |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | × | √ |
ly028-KeepLive
uni-app / uni-app x UTS 原生保活插件:防止 App 在后台被系统回收。支持 Android 前台服务 + WakeLock + 通知点击唤起 + JobScheduler / AlarmManager 周期拉活 + 开机恢复、iOS 后台定位 + 音频 + BGTaskScheduler + 本地通知、HarmonyOS 后台任务 + 常驻通知 + 后台定位 + 审计日志。
提供统一的 register / unregister / isRunning API,各平台差异通过 getCapabilities() 查询。
🛰 重磅新增:后台常驻持续定位上报(Android / iOS / 鸿蒙)
App 切到后台、锁屏、前端 JS 被挂起回收,甚至进程被杀后由保活拉活,原生仍按间隔持续采集定位并上传到你的服务器。
完整功能、接口、接入步骤请看专栏 👉 后台常驻持续定位上报专栏
⚠️ 鸿蒙用户必读:宿主工程必须配置
harmony-configs,否则后台无法常驻上报 👉 鸿蒙宿主必配🔗 建议与保活一起使用,被杀后自动拉活并恢复上报 👉 与保活配合使用
📸 三端实测(测试后端实时收到 Android / iOS / 鸿蒙上报)
⬇ 点击下载演示视频(mp4)
点击下载体验
扫码体验
平台支持
| 工程类型 | Android | iOS | HarmonyOS |
|---|---|---|---|
| uni-app App | ✅ | ✅ | ✅ |
| uni-app x App | ✅ | ✅ | ✅ |
| 保活能力 | Android | iOS | HarmonyOS |
|---|---|---|---|
| 前台服务(常驻通知) | ✅ | ⚠️ 本地通知(退后台可见) | ✅(通知栏常驻) |
| WakeLock CPU 唤醒 | ✅ | — | ✅(RunningLock) |
| 通知栏显隐控制 | ✅ | — | — |
| 通知点击唤起应用 | ✅ | — | — |
| 动态更新通知内容 | ✅ | ✅ | ✅ |
| 忽略电池优化引导 | ✅ | ✅(跳转系统设置) | ✅(跳转系统电池页) |
| 通知权限检查与引导 | ✅ (API 33+) | ✅ (UNUserNotificationCenter) | — |
| 跳转通知设置 | ✅ | ✅ | — |
| JobScheduler/WorkScheduler 周期拉活 | ✅ (JobScheduler) | ✅ (BGTaskScheduler) | ⚠️(SDK 适配中) |
| AlarmManager 闹钟拉活 | ✅ | — | — |
| 精确闹钟权限引导 (API 31+) | ✅ | — | — |
| 划掉最近任务不杀 Service | ✅ | — | — |
| 隐藏/显示最近任务 | ✅ | — | — |
| 应用退到后台 | ✅ | — | — |
| 启动时间 / 运行时长 | ✅ | — | — |
| 拉活任务持久化与恢复 | ✅ | — | — |
| 本地配置恢复 (restoreKeepAlive) | ✅ | ✅ | ✅ |
| 后台定位更新 | ✅ | ✅ | ✅ |
| 无声音频保活 | — | ✅ | ⚠️(SDK 适配中) |
| 后台任务延迟挂起 | — | ✅ (BGTaskScheduler) | ✅ |
| 服务自重启 (START_STICKY) | ✅ | — | — |
| 开机自启恢复 | ✅ | ❌ 系统不支持 | ⚠️(实验性) |
| 审计日志 | ✅ | ✅ | ✅ |
| OEM 省电策略引导 | ✅ (15+ 厂商) | ✅(通用引导) | ✅(华为引导) |
| 后台常驻持续定位上报(专栏) | ✅ | ✅ | ✅(需 harmony-configs) |
| 上报离线队列 + 失败重试 | ✅ | ✅ | ✅ |
| 被杀拉活后自动恢复上报 | ✅ | ✅(启动钩子 / 位置唤醒) | ✅(模块加载) |
- 环境:uni-app 建议 HBuilderX 3.7.2+;uni-app x 建议 HBuilderX 4.0+(鸿蒙建议 4.31+)
- 调试:原生 UTS 插件必须进入 自定义调试基座 或 正式云打包 才能运行;普通标准基座不包含本插件原生代码
- 定价:插件市场 免费
快速开始
1. 安装
在 DCloud 插件市场 搜索 ly028-KeepLive,导入到项目 uni_modules 后:
- 确认
manifest.json已配置正确的 AppID - 制作自定义调试基座 → 运行到自定义基座(真机)
- 各平台按 平台配置 章节完成额外配置
2. uni-app x / UTS 调用
import { register, unregister, isRunning } from '@/uni_modules/ly028-KeepLive'
import type { KeepAliveOptions } from '@/uni_modules/ly028-KeepLive'
// 启动保活
register({
channelId: 'keepalive_channel',
channelName: '保活服务',
title: 'App 运行中',
content: '正在保持后台运行,不会影响您使用其他应用'
})
// 检查状态
const alive = isRunning()
console.log('保活状态:', alive)
// 停止保活
unregister()
3. uni-app (Vue2/Vue3) 调用
import { register, unregister, isRunning } from '@/uni_modules/ly028-KeepLive'
register({
channelId: 'keepalive_channel',
channelName: '保活服务',
title: 'App 运行中',
content: '正在保持后台运行'
})
API
register(options) → void
注册保活服务。Android 自动获取 WakeLock 并启动前台服务;iOS 注册 BGTaskScheduler + 请求通知权限 + 持久化标记;鸿蒙申请后台任务 + 常驻通知 + CPU 唤醒 + 开机监听。各平台都接受 debug 参数控制日志输出。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| channelId | String | Android/鸿蒙 | 通知渠道 ID(Android 8.0+ 必需) |
| channelName | String | Android/鸿蒙 | 通知渠道名称 |
| channelDescription | String | 否 | 通知渠道描述(Android 8.0+ 系统设置中可见) |
| title | String | ✅ | 通知栏标题 |
| content | String | ✅ | 通知栏内容 |
| icon | Number | 否 | Android: 通知小图标资源 ID(默认使用应用图标) |
| debug | Boolean | 否 | 是否输出插件调试日志,默认 false(UTS 层全静默;Kotlin 原生日志见 changelog 说明) |
| enableInterruptNotification | Boolean | iOS | 是否启用「运动已中断」本地通知横幅(默认 true);点横幅重开 App 后 register() 自动恢复全部保活 |
| interruptDelaySeconds | Number | iOS | 中断通知延迟(秒,默认 60);注册时持久化,恢复时读回自定义值 |
| interruptTitle | String | iOS | 中断通知标题(默认 运动已中断) |
| interruptBody | String | iOS | 中断通知正文(默认 点击恢复运动) |
unregister() → void
注销保活服务。释放 WakeLock、停止前台服务、取消后台任务。
isRunning() → Boolean
检查保活服务是否正在运行。
getCapabilities() → KeepAliveCapability
获取当前平台的保活能力列表。
import { getCapabilities } from '@/uni_modules/ly028-KeepLive'
const caps = getCapabilities()
console.log(caps.foregroundService) // Android/HarmonyOS: true, iOS: false
console.log(caps.backgroundLocation) // Android / iOS / HarmonyOS: true
返回字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| foregroundService | Boolean | 前台服务常驻通知 |
| wakeLock | Boolean | CPU 唤醒锁 |
| backgroundLocation | Boolean | 后台定位保活 |
| backgroundAudio | Boolean | 无声音频保活 |
| backgroundTask | Boolean | 后台任务延迟挂起 |
| bootCompleted | Boolean | 开机自启恢复 |
| notificationClickable | Boolean | 通知点击唤起应用 |
| jobSchedulerRevive | Boolean | JobScheduler 定时拉活 |
| alarmRevive | Boolean | AlarmManager 闹钟拉活 |
| stopWithTaskPersist | Boolean | 划掉最近任务不销毁 Service |
| batteryOptimizationGuide | Boolean | 引导忽略电池优化 |
| notificationPermissionCheck | Boolean | 通知权限检查 (API 33+) |
| excludeFromRecents | Boolean | 隐藏/显示最近任务 |
| updateNotificationContent | Boolean | 动态更新通知内容 |
| exactAlarmSchedule | Boolean | 精确闹钟 (API 31+) |
| moveToBackground | Boolean | 应用退到后台 |
| pluginStartTime | Boolean | 获取插件启动时间戳 |
| restoreKeepAlive | Boolean | 从本地配置恢复保活 |
Android 特有 API
import {
openBatteryOptimizationSettings,
getNotificationVisible,
setNotificationVisible,
checkNotificationPermission,
openNotificationSettings,
restoreKeepAlive,
unregisterAndClear,
startPeriodicTask,
stopPeriodicTask,
isPeriodicTaskRunning,
getLastPeriodicTaskError,
startAlarmRevive,
stopAlarmRevive,
isAlarmReviveRunning,
getLastAlarmReviveError,
canScheduleExactAlarms,
openExactAlarmSettings,
restoreReviveTasksFromPrefs,
getAndroidKeepAliveState,
getOemBatteryGuidance,
getKeepAliveReviveLog,
getPluginStartTime,
getPluginRunningDurationMs,
moveAppToBackground,
setExcludeFromRecents,
updateNotificationContent,
checkLocationPermission,
startLocation,
stopLocation
} from '@/uni_modules/ly028-KeepLive'
// 跳转电池优化设置(Android 6+)
// 引导用户将本应用设为「不优化」
openBatteryOptimizationSettings()
// 通知栏可见性控制
const visible = getNotificationVisible() // 当前是否显示通知
setNotificationVisible(false) // 隐藏通知(仅 WakeLock 保活)
setNotificationVisible(true) // 重新显示通知
// 通知权限检查(Android 13+)
const granted = checkNotificationPermission()
if (!granted) {
openNotificationSettings() // 跳转应用通知设置页
}
// 从已保存配置自动恢复保活(用于 App 启动后同步状态)
const restored = restoreKeepAlive()
// 注销保活 + 清除开机自启配置(重启后不再自动恢复)
unregisterAndClear()
// ===== 定位保活(Android,与 iOS API 对齐)=====
// 检查定位授权状态(返回中文描述:"已拒绝" / "使用期间" / "已授权")
const locStatus = checkLocationPermission()
// 启动定位保活:使用系统 LocationManager 持续定位维持进程,
// 并给前台服务附加 location 类型实现后台定位保活。
// 未授权时自动弹出系统权限请求,用户授权后【自动开始】,无需二次调用。
// 第二个参数为持续回调:每隔 interval 秒把最近一次定位以 LocationResult JSON 回调给前端。
startLocation({
distanceFilter: 100, // 位置更新最小距离(米),默认 100
interval: 5, // 持续回调间隔(秒),默认 5
title: '定位保活运行中', // 传入 title 时会请求通知权限并在通知栏展示
subtitle: '正在后台持续定位', // 通知副标题(可选)
// manualStart: true, // 手动启动时弹后台定位引导(默认 true)
// backgroundLocationDialogTitle: '需要后台定位权限',
// backgroundLocationDialogMessage: '为了在息屏后持续记录位置,请允许后台定位'
}, (res) => {
const loc = JSON.parse(res) // 结构为 LocationResult,三端字段一致
console.log(loc.latitude, loc.longitude, loc.speed, loc.altitude, loc.address)
})
// 停止定位保活(若前台服务由 startLocation 独立拉起,会一并停止)
stopLocation()
LocationResult 字段(三端一致,通过回调 JSON 下发;平台缺失字段为默认值 0/""):
| 字段 | 说明 |
|---|---|
latitude / longitude |
经纬度(度) |
altitude |
海拔(米) |
accuracy / verticalAccuracy |
水平 / 垂直精度(米) |
speed / speedAccuracy |
速度 / 速度精度(米/秒) |
bearing / bearingAccuracy |
方向角 / 精度(度,iOS course / Harmony direction) |
timestamp |
定位时间(毫秒 epoch) |
provider |
来源:Android 为系统 provider(gps / network / passive);iOS / 鸿蒙系统不提供来源,固定 "gps" |
address |
逆地理编码地址(尽力而为,取不到为 "") |
| 函数 | 说明 |
|---|---|
openBatteryOptimizationSettings() |
引导忽略电池优化(无参对外不变;内部已豁免可跳列表,失败有回退) |
checkBatteryOptimization() → boolean |
是否已忽略电池优化(API 23+) |
openBatteryOptimizationListSettings() → SettingsOpenResult |
打开系统电池优化列表页 |
getNotificationVisible() → boolean |
获取当前前台服务通知是否可见 |
setNotificationVisible(visible) |
显示/隐藏前台服务常驻通知(隐藏后 WakeLock 持续保活) |
checkNotificationPermission() → boolean |
检查通知是否可用(合并系统通知开关 + API 33 POST_NOTIFICATIONS) |
openNotificationSettings() |
去开通知相关设置(内部优先通知设置页,失败回退应用详情) |
openAppNotificationSettings() |
打开应用通知设置页 |
requestNotificationPermission() → boolean |
API 33+ 弹出系统授权(内部走 UTSAndroid.requestSystemPermission);否则/无 Activity 时跳转设置 |
canOpenOemAutoStartSettings() → boolean |
当前 ROM 是否能解析到自启动设置页 |
openOemAutoStartSettings() → SettingsOpenResult |
优先本应用详情/单应用页;失败再兜底 |
openOemAutoStartListSettings() → SettingsOpenResult |
显式打开厂商自启动「应用列表」 |
canOpenOemBatterySaverSettings() → boolean |
是否能解析到厂商省电设置页 |
openOemBatterySaverSettings() → SettingsOpenResult |
跳转厂商省电/后台限制设置 |
getAndroidAuthorizationStatus() → AndroidAuthorizationStatus |
授权体检:电池/通知/闹钟/OEM 等 |
markAutoStartUserConfirmed() → boolean |
用户手动确认已开启自启动(无法程序检测时的替代) |
restoreKeepAlive() → boolean |
从 SharedPreferences 读取配置并自动恢复保活,用于 App 启动后同步开机自启状态 |
unregisterAndClear() |
注销保活 + 清除 SharedPreferences,重启后不会自动恢复(区别于 unregister() 仅停止保活不清除配置) |
startPeriodicTask(intervalMinutes) → boolean |
启动 JobScheduler 周期拉活(最小 15 分钟;成功写入 SP,重启后可恢复) |
stopPeriodicTask() |
停止 JobScheduler |
isPeriodicTaskRunning() → boolean |
定时任务是否在运行 |
getLastPeriodicTaskError() → string |
最近一次定时任务失败原因 |
startAlarmRevive(intervalMinutes) → boolean |
启动 AlarmManager 闹钟拉活(API 31+ 需精确闹钟权限) |
stopAlarmRevive() |
停止闹钟拉活 |
isAlarmReviveRunning() → boolean |
闹钟拉活是否在运行 |
getLastAlarmReviveError() → string |
最近一次闹钟拉活失败原因 |
canScheduleExactAlarms() → boolean |
API 31+ 是否可调度精确闹钟 |
openExactAlarmSettings() |
跳转系统「闹钟与提醒」/精确闹钟权限设置 |
restoreReviveTasksFromPrefs() → string |
从 SP 恢复已保存的定时任务、闹钟与定位保活(App 启动或开机后调用,返回日志摘要) |
getAndroidKeepAliveState() → AndroidKeepAliveState |
只读快照:running / notificationVisible / periodicTaskRunning / alarmReviveRunning / bootConfigSaved / locationRunning,供 UI 同步状态 |
getOemBatteryGuidance() → OemBatteryGuidance |
返回 { brand, manufacturer, guideContent } 厂商省电引导,供前端自定义弹窗/UI;未识别时 brand/manufacturer 为 other |
getKeepAliveReviveLog() → KeepAliveReviveEvent[] |
拉活审计日志(仅 register debug=true 时记录):timestamp / source / action / result / detail |
getPluginStartTime() → number |
最近一次 register 成功的时间戳(毫秒) |
getPluginRunningDurationMs() → number |
保活已运行时长(毫秒) |
moveAppToBackground() |
应用退到后台(不结束进程) |
setExcludeFromRecents(exclude) |
隐藏/显示最近任务列表项 |
updateNotificationContent(title, content) |
更新通知栏文案(须已 register 且通知已显示) |
checkLocationPermission() → string |
检查定位授权状态(中文描述:"已拒绝" / "使用期间" / "已授权") |
startLocation(options?, onLocation?) |
启动定位保活;未授权自动弹权限并在授权后自动开始;distanceFilter 默认 100 米,interval 默认 5 秒;传 title/subtitle 时请求通知权限并展示前台通知;前台授予后会弹出 native 提示框引导授权后台定位(manualStart=true 时,默认 true;自动拉活场景传 false);支持 backgroundLocationDialogTitle / backgroundLocationDialogMessage 自定义弹窗文案(不传用默认);成功后写入 SP,重启可恢复;onLocation 为持续回调(LocationResult JSON) |
stopLocation() |
停止定位保活并清除 SP 恢复标志(由 startLocation 独立拉起的前台服务会一并停止) |
说明:
register()后若通知已显示,点击通知可唤起应用主界面(ContentIntent)。- 定时任务 / 闹钟拉活为辅助手段,须先
register();配置持久化后,开机与restoreKeepAlive()会一并尝试恢复。
Android 保活手段矩阵
| 保活手段 | Android 版本 | 原理 | 所需权限 | 政策与风险 | 插件 API |
|---|---|---|---|---|---|
| 前台服务 specialUse | 21+(8.0+ 需渠道) | 提升进程优先级,常驻通知 | FGS / FGS_SPECIAL_USE / POST_NOTIFICATIONS(33+) | Play 需声明 specialUse | register() |
| 通知点击唤起 | 21+ | ContentIntent 打开主 Activity | 无 | 低 | register() 后自动生效 |
| WakeLock | 21+ | PARTIAL_WAKE_LOCK 防 CPU 休眠 | WAKE_LOCK | 需说明耗电 | register() |
| START_STICKY | 21+ | 服务被杀后系统尝试重启 | 无 | 低 | 内置 |
| 开机自启 | 21+ | BOOT / LOCKED_BOOT / QUICKBOOT 恢复 FGS | RECEIVE_BOOT_COMPLETED | 厂商可能拦截,需自启动白名单 | register() + BootReceiver |
| stopWithTask=false | 21+ | 划掉最近任务不销毁 Service | 无 | 低 | manifest |
| onTaskRemoved 自拉起 | 21+ | 划掉任务后节流再起 FGS | 无 | 激进 ROM 可能整进程杀死 | 内置 |
| JobScheduler 拉活 | 21+ | 周期尝试启动 FGS | 无 | 辅助手段,勿单独依赖 | startPeriodicTask() |
| AlarmManager 拉活 | 23+(31+ 精确需授权) | 定点唤醒尝试启动 FGS | SCHEDULE_EXACT_ALARM(31+) | 需用户授权精确闹钟 | startAlarmRevive() |
| 电池优化白名单 | 23+ | 降低 Doze 限制(弹窗+列表) | REQUEST_IGNORE_BATTERY_OPTIMIZATIONS | 需正当理由 | openBatteryOptimizationSettings() / openBatteryOptimizationListSettings() |
| OEM 自启动/省电跳转 | 21+ | 多 Intent 候选跳转厂商设置 | 无 | 无法程序检测是否已开启 | openOemAutoStartSettings() 等 |
| WorkManager | — | androidx 封装周期任务 | — | 后续版本 | 文档预留 |
iOS 特有 API
import {
startLocation, stopLocation, startMusic, stopMusic,
checkLocationPermission, checkNotificationPermission,
openNotificationSettings, restoreKeepAlive,
getIOSKeepAliveState, restoreIOSActivities,
updateNotificationContent, getKeepAliveReviveLog
} from '@/uni_modules/ly028-KeepLive'
// 定位保活(需用户授予「始终允许」定位权限)
// 第二个参数为持续回调:每隔 interval 秒把最近一次定位以 LocationResult JSON 回调给前端。
startLocation({
distanceFilter: 100, // 更新距离(米),默认 100
desiredAccuracy: 100, // 精度,默认 kCLLocationAccuracyHundredMeters
interval: 5 // 持续回调间隔(秒),默认 5
}, (res) => {
const loc = JSON.parse(res) // LocationResult,字段同 Android 表
console.log(loc.latitude, loc.longitude, loc.speed, loc.address)
})
stopLocation()
// 音频保活(需在 Bundle 中放入 keepalive_silent.wav 无声音频文件)
startMusic()
stopMusic()
// 检查定位授权状态
const status = checkLocationPermission() // 返回中文描述
// 通知权限检查 + 跳转设置
const hasPermission = checkNotificationPermission()
if (!hasPermission) {
openNotificationSettings()
}
// 从本地配置恢复保活状态
const restored = restoreKeepAlive()
// 一键恢复 + 重挂定位回调(冷启动后调用;register 已自动恢复定位/音频,这里补挂 JS 回调)
// 返回恢复后的状态快照,可直接同步 UI
const st = restoreIOSActivities((res) => {
const loc = JSON.parse(res)
console.log(loc.latitude, loc.longitude)
})
console.log('定位:', st.locationActive, '音频:', st.musicActive, '回调间隔:', st.locationInterval)
// 只读状态查询(不重挂回调;locationActive/musicActive 为「运行时 OR 持久化意图」)
const state = getIOSKeepAliveState()
if (state.locationActive) {
// 可按需重调 startLocation 重挂 onLocation
}
// 发布本地通知(register 时会请求通知权限,退到后台或前台都会显示横幅)
updateNotificationContent('保活状态', '后台服务运行中')
// 获取拉活审计日志(需 register 时 debug: true)
const logs = getKeepAliveReviveLog()
| 函数 | 说明 |
|---|---|
startLocation(options?, onLocation?) |
启动后台定位保活,distanceFilter 默认 100 米,interval 默认 5 秒;onLocation 为持续回调(LocationResult JSON) |
stopLocation() |
停止后台定位 |
checkLocationPermission() → string |
检查定位授权状态(中文描述) |
startMusic() |
启动无声音频循环保活(需 keepalive_silent.wav) |
stopMusic() |
停止音频保活 |
checkNotificationPermission() → boolean |
检查通知授权状态 |
openNotificationSettings() |
跳转系统设置页面 |
restoreKeepAlive() → boolean |
从 UserDefaults 恢复保活状态(被杀前在运行时 → 用持久化中断配置重 register(),内部自动恢复定位/音频) |
restoreIOSActivities(onLocation?) → IOSKeepAliveState |
冷启动后一键恢复:被杀前在运行且未注册 → 自动重注册;定位生效 → 用持久化配置重挂 onLocation(幂等,不重复启动);音频生效 → 确保在播;返回恢复后的状态快照 |
getIOSKeepAliveState() → IOSKeepAliveState |
只读状态快照 { running, locationActive, musicActive, locationInterval };locationActive/musicActive 为「运行时 OR 持久化意图」,未触发恢复也能反映上次开启过的保活,供前端决定是否重挂回调 |
updateNotificationContent(title, content) |
发布一条本地通知(register 时会请求通知权限) |
getKeepAliveReviveLog() → string |
拉活审计日志 JSON(需 register debug:true) |
IOSKeepAliveState 字段:running(保活服务是否运行)、locationActive(定位保活是否生效)、musicActive(音频保活是否生效)、locationInterval(持久化的定位回调间隔秒,重挂 startLocation 时可直接用)。
iOS 恢复与自愈(进程被杀后自动恢复)
iOS 保活活动(register / 定位 / 音频 / 中断通知自定义文案)全部持久化在 UserDefaults,前端零存储、零状态维护,原生层以 UserDefaults 为单一事实源:
register()自动恢复:register()在注册前读取was_running标记;若上次被杀前保活在运行,自动从 UserDefaults 恢复定位保活与音频保活(带自愈守卫,已在运行时绝不重复启动)。因此点中断横幅重开与杀进程后点图标重开是同一条路径(都是冷启动 → App 入口自然调register()),前端无需区分场景。restoreKeepAlive():被杀前在运行时,用持久化的中断 4 参数重新register()(register 内部再自动恢复定位/音频)。restoreIOSActivities(onLocation?):一键恢复 + 重挂定位回调。内部按需执行「自动重注册 → 重挂定位回调 → 确保音频播放」,前端只需把新建的 JS 回调传进来。
真实 App 开发者冷启动恢复契约(App 入口 onShow 调一次即可,无任何存储):
import { isRunning, restoreKeepAlive, restoreIOSActivities } from '@/uni_modules/ly028-KeepLive'
onShow() {
if (!isRunning()) restoreKeepAlive() // 原生恢复 register + 定位 + 音频 + 中断配置
const st = restoreIOSActivities((res) => {
// res 为 LocationResult JSON,重挂的定位持续回调
})
if (st.musicActive) musicRunning = true // 按返回状态同步 UI
}
⚠️ 说明:上面的
register()/restoreKeepAlive()/restoreIOSActivities()恢复的是保活与定位保活,仍需 App 入口调用。1.4.0 新增的后台常驻定位上报不同:插件通过UTSiOSHookProxy启动钩子在 App 启动时自动恢复,无需前端调用任何接口,见 专栏。onLocation这类 JS 回调进程被杀即失效,上报场景请在页面 onLoad 用onBackgroundLocationUploadEvent重新订阅。
🛰 专栏:后台常驻持续定位上报(Android / iOS / 鸿蒙)
1.4.0 新增。一套 API 三端一致:前端配置一次,原生负责采集、缓存、上传、拉活恢复,与前端 JS 是否存活无关。
1. 解决什么痛点
uni-app 的前端 JS 在 App 退到后台、锁屏一段时间后会被挂起甚至回收,setInterval、uni.getLocation、uni.request 全部停摆;进程被系统杀掉后更是什么都不剩。常见的「前端定时取位置再上传」方案在后台基本不可用。
本功能把整条链路放进原生层:
- 采集:原生定位服务按
interval秒取样(Android 前台服务 / iOS 后台定位 / 鸿蒙长时任务) - 缓存:每个点先写入本地 SQLite 队列(最多 20000 条、保留 72 小时),断网不丢点
- 上传:原生 HTTP 批量或单点上传,失败自动退避重试
- 恢复:开关和配置持久化在原生,进程被杀后经保活拉活 / 开机 / 重新打开 App 自动恢复,不需要前端再调 start
2. 工作原理
定时取样(interval) → 过滤(精度/距离/异常速度) → 本地队列(SQLite)
→ 批量上传(batchUploadIntervalSec / 攒满 batchSize) 或 单点实时(batchSize=1)
→ 按服务端响应码处理:
2xx → 删除已传点
401 / 403 → 暂停上传(healthIssues 出现 server_unauthorized),重新 start 后恢复
400 / 413 / 422 → 移入失败区(不再重试,可用 records 查询)
408 / 429 / 5xx / 网络错误 → 指数退避重试(5 秒起,最长 5 分钟)
3. 5 分钟接入
第一步:开始上报(只需调用一次,之后被杀拉活都会自动恢复)
import {
startBackgroundLocationUploadAsync,
stopBackgroundLocationUpload,
getBackgroundLocationUploadStatus,
onBackgroundLocationUploadEvent,
offBackgroundLocationUploadEvent
} from '@/uni_modules/ly028-KeepLive'
startBackgroundLocationUploadAsync({
url: 'https://your.server.com/api/location/upload',
headers: JSON.stringify({ Authorization: 'Bearer xxx' }),
extra: JSON.stringify({ userId: '10086' }),
interval: 5, // 每 5 秒采一个点
batchUploadIntervalSec: 30, // 每 30 秒批量传一次
batchSize: 40, // 攒满 40 个点立即传
coordType: 'gcj02',
title: '位置上报中', // Android / 鸿蒙常驻通知文案
content: '正在后台记录轨迹'
}, null, (raw) => {
const r = JSON.parse(raw) // KeepLiveResult 信封
if (r.code === 0) console.log('上报已开始', r.msg)
else console.log('启动失败', r.subCode, r.msg, r.data)
})
第二步:页面订阅事件(每次页面打开 onLoad 调一次,拉活后也能接上)
export default {
onLoad() {
onBackgroundLocationUploadEvent((raw) => {
const ev = JSON.parse(raw) // { type, timestamp, data }
if (ev.type === 'point') console.log('新点', ev.data.latitude, ev.data.longitude)
if (ev.type === 'upload') console.log(ev.data.ok ? `上传成功 ${ev.data.count} 条` : `上传失败 HTTP ${ev.data.httpCode}`)
if (ev.type === 'state') console.log('运行中', ev.data.running, '原因', ev.data.reason, ev.data.source)
})
},
onUnload() {
offBackgroundLocationUploadEvent()
}
}
第三步:需要时停止
const r = JSON.parse(stopBackgroundLocationUpload()) // 停采集,尽力补传一次,剩余点保留到下次 start
uni-app x / UTS 写法相同,函数名与参数一致;
import type { BackgroundLocationUploadOptions } from '@/uni_modules/ly028-KeepLive'可获得类型提示。 原生插件需 自定义调试基座 或 云打包 才能运行。
4. 接口说明
| 函数 | 说明 |
|---|---|
startBackgroundLocationUploadAsync(options, onLocation, callback) |
开始上报。缺权限时原生依次引导授权(位置服务 → 前台定位 → 后台始终 → 通知),全部通过后开始。运行中再次调用 = 热更新配置(返回 updated,不重复弹授权)。onLocation 每个有效点推送一次 LocationResult JSON,可传 null;callback 一次性返回 KeepLiveResult JSON |
stopBackgroundLocationUpload() → string |
停止上报:停采集、尽力补传一次、剩余点保留到下次 start;唯一会关闭自动恢复开关的接口;不影响 register / startLocation |
getBackgroundLocationUploadStatus() → string |
只读状态,data 为 BackgroundLocationUploadStatus JSON |
getBackgroundLocationUploadRecordsAsync(query, callback) |
查询本地队列记录,data={"total":n,"records":[...]} |
onBackgroundLocationUploadEvent(callback) |
订阅事件:只订阅、不启动;全局唯一(重复调用覆盖上一个);stop 后仍保留;订阅后立即推一次 state 快照 |
offBackgroundLocationUploadEvent() |
取消订阅 |
4.1 BackgroundLocationUploadOptions
| 参数 | 类型 | 默认值 | 范围 | 说明 |
|---|---|---|---|---|
| url | string | — | — | 必填,http 或 https 上报地址 |
| method | string | POST |
POST / PUT | 请求方法 |
| headers | string | — | — | 自定义请求头 JSON 字符串,原生加密存储 |
| extra | string | {} |
— | 业务附加字段 JSON 对象字符串,原样放进请求体 extra |
| interval | number | 5 | 1~3600 | 采集间隔(秒):每隔多少秒取一次位置写入队列 |
| batchUploadIntervalSec | number | 30 | 5~3600 | 批量上传间隔(秒):每隔多少秒把队列里的点传一次 |
| batchSize | number | 40 | 1~100 | 每批最多点数;攒满立即传;设为 1 = 单点实时 |
| timeoutSec | number | 15 | 5~120 | 单次请求超时 |
| coordType | string | wgs84 |
wgs84 / gcj02 / bd09 | 上报坐标系(境外不转换) |
| accuracy | string | high |
high / balanced / low | 定位精度档位 |
| minAccuracyMeters | number | 200 | — | 水平精度差于此值的点丢弃 |
| uploadOnlyWhenChanged | boolean | false | — | true:与上个点距离小于 distanceFilter 时丢弃(静止不上报) |
| distanceFilter | number | 10 | 0~1000 | 最小位移(米),仅 uploadOnlyWhenChanged=true 时生效 |
| title / content | string | — | — | Android / 鸿蒙常驻通知文案 |
| backgroundLocationDialogTitle / backgroundLocationDialogMessage | string | 内置文案 | — | 「始终允许」后台定位引导弹窗文案 |
4.2 BackgroundLocationUploadStatus
| 字段 | 说明 |
|---|---|
| running | 是否上报中(含拉活恢复后) |
| pending | 待上报点数 |
| failed | 失败区点数(400/413/422 等不可重试) |
| lastSuccessAt | 最近一次上报成功时间(毫秒,0 表示无) |
| lastHttpCode | 最近一次 HTTP 状态码(0 表示网络错误或未请求) |
| lastError | 最近一次错误描述 |
| healthIssues | 影响稳定性的问题列表,见 第 11 节 |
4.3 队列记录查询
query:{ status: 'pending' | 'failed' | 'all'(默认), offset: 0, limit: 100(最大 500) }
记录字段:id(UUID,服务端可去重)、status、point(点位 JSON,同请求体 points 元素)、createdAt、retryCount、lastAttemptAt、lastHttpCode、lastError。
4.4 事件格式(onBackgroundLocationUploadEvent)
事件为 JSON 字符串:{ "type": "point" | "upload" | "state", "timestamp": 毫秒, "data": {...} }
| type | 何时推送 | data |
|---|---|---|
| point | 每采到一个有效点 | LocationResult(同 onLocation,含 sampledAt / stale) |
| upload | 每批发送后一次(成功 / 失败 / 暂停都推) | { ok, count, httpCode, error, pending, failed } |
| state | 订阅时、开始、热更新、拉活恢复、停止 | { running, reason, source, pending, failed, lastSuccessAt } |
state.reason:subscribed(订阅快照)/ started / updated / restored(拉活恢复,source 为恢复来源)/ stopped。
onLocation与事件监听都会收到点位,二选一即可,同时用会重复。推荐:start 时onLocation传null,点位统一走事件监听。
5. 统一返回信封与错误码
所有新接口的同步返回值与 callback 都是 KeepLiveResult JSON:{ code, subCode, msg, data }
code=0成功;code=1失败msg已按系统语言翻译,可直接 toastdata为业务 JSON 字符串(需再JSON.parse)
| subCode | 含义 |
|---|---|
| 400 | 参数错误(如 url 非法)或授权流程进行中重复调用 |
| 403 | 权限不足,data={"permission","reason"} |
| 404 | 资源不存在 |
| 500 | 内部错误 |
| 501 | 平台不支持 |
| 502 | 上游 HTTP 非 2xx |
| 503 | 网络不通 |
403 时 data.permission 取值:location_service(系统位置开关)/ location / location_background / notification;data.reason 取值:denied / denied_forever / restricted / no_ui。
6. 上报请求体(服务端需要实现的接口)
原生向 url 发送 Content-Type: application/json:
{
"platform": "Android",
"extra": { "userId": "10086" },
"points": [
{
"id": "3f2c...uuid",
"lat": 30.5285609, "lng": 104.0063613, "coordType": "gcj02",
"accuracy": 12.5, "altitude": 500.1, "speed": 0.0, "bearing": 0.0,
"timestamp": 1792000000000, "sampledAt": 1792000001000, "stale": false,
"provider": "gps", "isMock": false,
"battery": 96, "network": "wifi", "appState": "background", "source": "fgs"
}
]
}
| 字段 | 说明 |
|---|---|
| platform | Android / iOS / Harmony |
| extra | start 时传入的 extra |
| id | 点位 UUID,重试时不变,服务端可据此去重 |
| lat / lng / coordType | 已按 coordType 转换后的坐标 |
| timestamp | 系统定位时间(毫秒) |
| sampledAt | 取样时间(毫秒) |
| stale | 旧位置重复上报(sampledAt - timestamp > max(2×interval, 30s),如静止或室内无新定位) |
| provider | Android 为系统 provider(gps / network / passive);iOS / 鸿蒙系统不提供来源,固定 gps |
| isMock | 是否模拟定位(Android) |
| battery | 电量百分比(-1 表示取不到;iOS 系统按 5% 一档) |
| network | wifi / cellular / ethernet / other / none / unknown |
| appState | foreground / background |
| source | 采集时的后台机制(如 Android fgs、iOS location、鸿蒙 continuous_task) |
服务端返回 2xx 即视为成功,响应体内容不做要求。其他状态码按上文「2. 工作原理」处理。
本地测试:插件源码仓库的
backend/提供 Node 测试服务(可模拟 200 / 401 / 500 / 超时),网页实时查看收到的请求与点位。
三端实测截图(测试后端实时收到 Android / iOS / 鸿蒙上报的请求与点位):
演示视频:点击下载演示视频(mp4)
7. 两个间隔与上传模式
| 概念 | 参数 | 作用 |
|---|---|---|
| 采集间隔 | interval |
每隔多少秒取一次位置写入本地队列 |
| 批量上传间隔 | batchUploadIntervalSec |
每隔多少秒把队列里的点批量传一次 |
| 每批条数 | batchSize |
队列攒满即立即上传,不等间隔 |
例:interval=5 + batchUploadIntervalSec=30 → 每 5 秒采一个点,约每 30 秒一次请求、每次约 6 个点。
| 模式 | 配置 | 特点 |
|---|---|---|
| 批量上传(推荐) | batchSize=40、batchUploadIntervalSec=30 |
请求少,省电省流量 |
| 单点实时 | batchSize=1、batchUploadIntervalSec=interval(最小 5) |
每采一个点立即传一条,实时性高,请求多、耗电高;batchUploadIntervalSec 只作断网 / 退避后的兜底补传 |
8. 采集方式
三端一致采用定时取样:系统定位回调只更新「最近位置」,每 interval 秒取一次最近位置(没有新定位时取系统缓存的上次位置,并标记 stale=true)送过滤后入队。
uploadOnlyWhenChanged=false(默认):静止 / 室内也按间隔出点uploadOnlyWhenChanged=true:与上次入队点距离小于distanceFilter的点丢弃,静止时基本不出点- 尚未拿到任何位置时不上报;启动超过
max(2×interval, 60s)仍无位置,healthIssues出现no_location_fix
9. 一键授权流程
调用 startBackgroundLocationUploadAsync 时,缺什么权限就按顺序引导什么,全部通过才开始:
| 步骤 | Android | iOS | 鸿蒙 |
|---|---|---|---|
| 系统位置开关 | 跳系统定位设置 | 提示去设置开启 | requestGlobalSwitch 系统弹窗 |
| 前台定位 | 运行时权限弹窗 | 「使用 App 期间」弹窗 | 模糊 + 精确定位弹窗 |
| 后台定位(始终允许) | Android 10+ 引导弹窗 → 设置页 | 「始终允许」升级弹窗 | requestPermissionOnSetting 设置弹窗 |
| 通知 | Android 13+ 弹窗 | 通知授权弹窗 | 通知授权弹窗 |
任一步拒绝返回 subCode=403。拉活恢复路径不会弹任何窗,缺权限时只写入 healthIssues。
10. 🔗 与保活配合使用(强烈建议)
10.1 为什么要配合
上报功能自身已经带有后台保持手段(Android 独立前台服务、iOS 后台定位、鸿蒙长时任务),只要进程活着就会一直上报。但用户划掉 App、系统内存回收、厂商强杀后进程没了,上报也就停了。
保活插件的各种拉活手段(Android 开机广播、JobScheduler、AlarmManager、WorkManager、亮屏解锁、划卡重启、前台服务 sticky 重建……)负责把进程拉回来;进程一回来,上报模块自动检测并恢复。两者配合 = 被杀 → 拉活 → 自动恢复上报。
10.2 拉活后如何自动恢复
- start 时,上报配置与开关持久化在原生(Android SharedPreferences / iOS UserDefaults / 鸿蒙 preferences;headers 加密存储)
- 任何入口拉起进程时,按「开关为开 + 有配置 + 有定位权限」静默恢复,不弹窗、不依赖前端 JS
- 只有
stopBackgroundLocationUpload()会关闭开关;unregister()停保活不影响上报,stopBackgroundLocationUpload()也不影响保活
| 平台 | 恢复入口(事件 state.source) |
|---|---|
| Android | keepalive_service(保活前台服务每次启动,覆盖保活全部拉活手段)、app_create(应用启动钩子)、boot、job、alarm、workmanager、screen_*(亮屏 / 解锁)、task_removed(划掉任务)、sticky(上报服务被系统重建) |
| iOS | launch(启动钩子,含显著位置变化 / 到访 / 区域事件把 App 唤醒)、bgtask(后台任务补传) |
| 鸿蒙 | module_load(插件模块被加载,宿主需在 App.vue 或启动页 import 插件) |
10.3 推荐调用方式
import { register, startBackgroundLocationUploadAsync, onBackgroundLocationUploadEvent } from '@/uni_modules/ly028-KeepLive'
// 1. 开保活(只需一次,配置会持久化)
register({ channelId: 'keepalive_channel', channelName: '保活服务', title: 'App 运行中', content: '保持后台运行' })
// Android 可再开辅助拉活:startPeriodicTask(15) / startAlarmRevive(15),并引导电池优化白名单、厂商自启动
// 2. 开上报(只需一次,之后拉活自动恢复)
startBackgroundLocationUploadAsync({ url: 'https://your.server.com/upload' }, null, (raw) => {})
// 3. 页面每次打开都订阅事件
onBackgroundLocationUploadEvent((raw) => { /* 更新页面 */ })
10.4 拉活后前端页面怎么接上
被杀拉活后,旧的 JS 环境和 start 时传的 onLocation 都已销毁,但原生上报已经在跑。用户点通知 / 图标进入 App 后,页面 onLoad 里调用 onBackgroundLocationUploadEvent:
- 立即收到
state快照(reason=subscribed,running=true,带待传 / 失败条数) - 之后持续收到
point/upload事件,页面即可继续刷新 - 不需要、也不应该再调一次 start(再调会被当作热更新)
10.5 注意事项
- Android 两条常驻通知:保活通知 + 上报通知(通知 ID 10031,渠道「后台定位上报」,文案取 options.title / content),属于正常现象
- Android 应用启动钩子(
app_create)需重新制作自定义基座 / 云打包后生效;离线打包需在宿主app/build.gradle的UTSHooksClassArray中登记uts.sdk.modules.ly028KeepLive.Ly028KeepLiveAndroidHook - iOS:被系统回收后靠显著位置变化等事件唤醒恢复,需「始终允许」定位;用户在多任务界面上滑强杀后,系统不会再唤醒,需用户重新打开 App
- 鸿蒙:无开机自启;进程被杀后需用户重新打开 App(插件模块加载即恢复);上报中被杀约 30 分钟后系统会弹「后台定位上报已中断」提醒
- 厂商强杀(尤其国产 ROM)仍需引导用户加入电池优化白名单 / 自启动白名单,可用
getOemBatteryGuidance()获取引导文案
11. 健康体检 healthIssues
getBackgroundLocationUploadStatus() 的 healthIssues 列出影响稳定性的问题,可据此引导用户:
| 取值 | 平台 | 含义 / 处理建议 |
|---|---|---|
location_service_disabled |
三端 | 系统位置开关关闭 → 引导开启 |
location_denied |
三端 | 定位权限被拒 → 引导去设置开启 |
location_background_denied |
三端 | 没有「始终允许」 → 后台会停,引导开启 |
location_precise_denied |
三端 | 仅模糊定位 → 引导开启精确位置 |
notification_disabled |
Android / 鸿蒙 | 通知关闭 → 常驻通知不可见,可能更易被杀 |
location_collector_failed |
三端 | 定位订阅一个都没成功 |
no_location_fix |
三端 | 启动较久仍无任何位置(室内 / 信号差) |
no_network |
Android / 鸿蒙 | 当前无网络,点位暂存队列 |
server_unauthorized |
Android | 服务端返回 401 / 403,上传已暂停,更新 headers 后重新 start |
headers_unencrypted |
Android / 鸿蒙 | 系统加密不可用,headers 降级明文存储 |
battery_optimization |
Android | 未加入电池优化白名单 → openBatteryOptimizationSettings() |
exact_alarm_denied |
Android | 未授予精确闹钟 → openExactAlarmSettings() |
oem_auto_start_unconfirmed |
Android | 未确认厂商自启动 → openOemAutoStartSettings() |
foreground_service_start_failed |
Android | 上报前台服务启动失败 |
background_restricted |
Android | 用户在系统里限制了后台活动 |
power_save_mode |
Android | 省电模式开启 |
app_standby_restricted |
Android | 待机分组为 RARE / RESTRICTED |
permission_auto_revoke_enabled |
Android 11+ | 长期不用会自动撤销权限 → 引导在应用详情关闭「移除权限」 |
notification_channel_disabled |
Android | 上报通知渠道被关闭 |
background_refresh_disabled |
iOS | 后台 App 刷新关闭 → BGTask 补传不可用 |
low_power_mode |
iOS | 低电量模式开启 |
continuous_task_failed |
鸿蒙 | 长时任务申请失败,几乎都是宿主没配 harmony-configs |
12. ⚠️ 鸿蒙宿主必配:harmony-configs(不配置则后台无法常驻上报)
🚨 重要:鸿蒙后台持续定位依赖「长时任务(location 类型)」,华为要求在宿主应用的 EntryAbility 上声明
backgroundModes: ["location"]。插件无法替你声明,必须由使用插件的宿主工程自己配置!
为什么插件不能代配:插件以 HAR 形式合并,只能声明权限,无法修改宿主 EntryAbility 的属性(插件内写同名 Ability 会因缺 srcEntry / startWindowIcon / startWindowBackground 等字段编译失败,已实测)。插件需要的权限(KEEP_BACKGROUND_RUNNING、LOCATION、LOCATION_IN_BACKGROUND、INTERNET、GET_NETWORK_INFO、PUBLISH_AGENT_REMINDER 等)已由插件自动合并,宿主不必重复声明。
配置步骤:
- 在 uni-app 项目根目录新建文件:
harmony-configs/entry/src/main/module.json5(DCloud 官方 harmony-configs 机制,该文件会整文件覆盖编译生成的 entry 配置) - 复制下面完整内容(以插件示例工程同路径文件为准),关键是 EntryAbility 里的
backgroundModes:
{
"module": {
"name": "entry",
"type": "entry",
"description": "$string:module_desc",
"mainElement": "EntryAbility",
"deviceTypes": [
"phone"
],
"deliveryWithInstall": true,
"installationFree": false,
"pages": "$profile:main_pages",
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:layered_image",
"label": "$string:EntryAbility_label",
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
// ↓↓↓ 必须:后台定位长时任务 ↓↓↓
"backgroundModes": [
"location"
],
"skills": [
{
"entities": [
"entity.system.home"
],
"actions": [
"action.system.home"
]
}
]
}
],
"requestPermissions": [
{
"name": "ohos.permission.INTERNET"
}
]
}
}
- 如果你的项目已有该文件(比如配置过其他 Ability 属性),只需在 EntryAbility 里加上
"backgroundModes": ["location"],不要整段替换掉自己的配置 - 同时使用保活的音频能力时写成
["location", "audioPlayback"] - 重新运行到鸿蒙 / 重新打包
如何确认生效:
- 已生效:开始上报后状态栏出现长时任务通知,
getBackgroundLocationUploadStatus().healthIssues不含continuous_task_failed - 未生效:
healthIssues含continuous_task_failed,日志提示退化为短时任务,退到后台几分钟后上报停止
另外两点鸿蒙必做:
- App.vue 或启动页必须 import 插件(例如
import { getBackgroundLocationUploadStatus } from '@/uni_modules/ly028-KeepLive'),插件模块被加载时才会触发进程重启后的自动恢复 - 「后台定位上报已中断」提醒使用代理提醒,需在华为开发者后台为该包名申请代理提醒开放能力(
PUBLISH_AGENT_REMINDER);未获批时只是没有提醒,上报本身不受影响
13. 各端配置与上架注意
Android
- 插件已自动声明
INTERNET、ACCESS_NETWORK_STATE、定位、前台服务定位类型等权限 - http 明文地址:Android 9+ 默认禁止 http,生产环境请用 https;测试 http 需宿主允许 cleartext
- 上报前台服务通知 ID 10031,渠道「后台定位上报」
- 离线打包需在宿主
app/build.gradle加implementation 'androidx.work:work-runtime:2.9.1',并在UTSHooksClassArray中登记uts.sdk.modules.ly028KeepLive.Ly028KeepLiveAndroidHook(云打包 / 自定义基座自动处理)
iOS
- 插件
utssdk/app-ios/Info.plist已含:UIBackgroundModes(location / audio / fetch / processing)、BGTaskSchedulerPermittedIdentifiers(uni.ly028.keeplive.refresh、uni.ly028.keeplive.upload)、定位用途文案、NSLocationTemporaryUsageDescriptionDictionary.BackgroundLocationUpload、ATS,云打包自动合并 - 定位用途文案请在自己项目的 manifest 中同步改成符合业务的描述,否则审核可能被拒
- 插件 Info.plist 开启了
NSAllowsArbitraryLoads(为支持 http 测试地址);上架前建议改用 https 并评估是否移除 - 插件隐私清单只声明 UserDefaults;你把位置上报到自己的服务器,需在宿主 App 隐私清单 / App Store 隐私标签中声明「精确位置」收集用途
- 冷启动恢复由启动钩子自动完成,无需前端调用任何恢复接口
- 被系统回收后由显著位置变化 / 到访 / 区域退出事件唤醒恢复,BGTask 负责补传
- 离线打包:插件 Info.plist 不会自动合并,需手动把上述键并入宿主 Info.plist;在
dcloud_uniplugins追加{ hooksClass: "UTSSDKModulesLy028KeepLiveLy028KeepLiveAppHook", plugins: [] };插件 framework 需在PDRCore initEngine之前加载;PrivacyInfo.xcprivacy手动并入
鸿蒙
- 见 第 12 节 harmony-configs(必配)
- 插件新增权限:
INTERNET、GET_NETWORK_INFO、PUBLISH_AGENT_REMINDER - 长时任务不可用时,退到后台会用一次短时任务把最后一批点传完
14. 坐标系
| coordType | 说明 |
|---|---|
wgs84 |
GPS 原始坐标(默认),适合 Google 地图 / 国际地图 |
gcj02 |
国测局坐标,适合高德 / 腾讯地图 |
bd09 |
百度坐标,适合百度地图 |
转换在原生完成,三端结果一致;境外坐标不转换。onLocation / 事件 point 推送的是 WGS84 原始坐标,只有上报到服务器的点按 coordType 转换。
15. 常见问题
Q:开始上报后服务端收不到请求?
A:① 是否自定义基座 / 云打包;② getBackgroundLocationUploadStatus() 看 lastHttpCode / lastError;③ Android http 地址是否被 cleartext 拦截;④ 手机与服务器网络是否互通;⑤ 批量模式要等 batchUploadIntervalSec 或攒满 batchSize 才发。
Q:App 被杀拉活后,点进页面什么回调都没有?
A:旧页面的回调已随 JS 销毁。页面 onLoad 调 onBackgroundLocationUploadEvent 重新订阅即可,见 10.4。
Q:鸿蒙退到后台几分钟就不传了?
A:99% 是没配 harmony-configs,healthIssues 会有 continuous_task_failed,见 第 12 节。
Q:iOS 被杀后不恢复? A:确认定位授权为「始终允许」;用户上滑强杀后 iOS 不会再唤醒,需重新打开 App(打开即自动恢复,无需调用 start)。
Q:静止不动时也在上报?
A:默认 uploadOnlyWhenChanged=false,静止也按间隔出点(stale=true 表示旧位置)。只想移动时上报请设为 true 并配合 distanceFilter。
Q:停止保活会停止上报吗?
A:不会。保活和上报相互独立,只有 stopBackgroundLocationUpload() 会停止上报并关闭自动恢复。
Q:电量 / 网络字段是真实值吗? A:是,均实时读取系统接口。iOS 电量按 5% 一档;模拟器电量常为 100、网络为 ethernet。
专栏结束。以下为保活功能的通用平台配置与注意事项。
平台配置
Android
插件已自动声明以下权限(在 AndroidManifest.xml):
| 权限 | 用途 |
|---|---|
FOREGROUND_SERVICE |
前台服务必要权限 |
FOREGROUND_SERVICE_SPECIAL_USE |
Android 12+ 特殊用途前台服务 |
WAKE_LOCK |
CPU 唤醒锁 |
RECEIVE_BOOT_COMPLETED |
开机自启 |
POST_NOTIFICATIONS |
Android 13+ 通知运行时权限 |
REQUEST_IGNORE_BATTERY_OPTIMIZATIONS |
忽略电池优化(6.0+) |
SCHEDULE_EXACT_ALARM |
精确闹钟(12+,AlarmManager 拉活) |
FOREGROUND_SERVICE_LOCATION |
Android 14+ 前台服务定位类型(定位保活) |
ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION |
前台定位(startLocation 需要) |
ACCESS_BACKGROUND_LOCATION |
Android 10+ 后台定位(「始终允许」,长期后台定位保活) |
INTERNET / ACCESS_NETWORK_STATE |
后台常驻定位上报(1.4.0) |
定位保活说明:
- 调用
startLocation()时,未授权会自动弹出定位权限请求,用户授权后自动开始定位(无需二次调用)。 - 传入
title时会同时请求通知权限(Android 13+),并以该标题在通知栏展示定位保活状态;前台服务会附加location类型。 - Android 10+:前台定位授予后,插件会内部再申请
ACCESS_BACKGROUND_LOCATION;若系统弹窗无「始终允许」或用户拒绝,可再引导到设置中手动开启(拒绝不阻断定位保活启动)。仅「使用期间」时,息屏长期后台定位可能受限。
开机与拉活任务恢复:
register()将保活配置写入 SharedPreferences。- 若已调用
startPeriodicTask()/startAlarmRevive()/startLocation()且成功,对应开关会写入 SP。 - 手机重启后
BootReceiver→ 恢复定位保活(若已开启)+ 前台服务 + JobScheduler + AlarmManager。定位恢复阶段无 JS 回调;App 再次打开后重调startLocation可重挂onLocation。 - App 冷启动可调用
restoreKeepAlive()同步前台服务,并调用restoreReviveTasksFromPrefs()恢复定时/闹钟/定位。
说明:开机自启恢复仅 Android;iOS/Harmony 无等价开机广播,需用户再次进入 App 后由业务侧决定是否重启定位。
拉活审计与 WakeLock 区别:
register({ debug: true })会将debug_enabled写入 SP;此后 Boot/Job/Alarm/START_STICKY 触发的前台 Service 恢复会写入getKeepAliveReviveLog()(debug: false时不记录)。- Job/Alarm/Boot 等不会在进程被杀后自动重新获取 WakeLock;WakeLock 仅在 App 进程内
register()/restoreKeepAlive()成功时记录wakelock_acquire事件。
Android 13+ (API 33) 通知权限说明:
Android 13 及以上版本将 POST_NOTIFICATIONS 列为运行时权限,用户可以在系统设置中开关。如果通知不显示:
- 使用
checkNotificationPermission()检查权限状态 - 未授予时调用
openNotificationSettings()跳转到应用通知设置页 - 用户手动开启后,重新注册前台服务即可显示常驻通知
插件采用「按需检查」策略:注册保活时不拦截通知权限,前台服务/通知控制按钮在点击时才动态检查并引导开启。
Android 6+ 电池优化说明:
部分厂商会强制休眠后台应用,即使有前台服务也可能受影响。建议引导用户:
- 调用
openBatteryOptimizationSettings()跳转到电池优化设置 - 将本应用设为「不优化」
iOS
插件自带 utssdk/app-ios/Info.plist,云打包 / 自定义基座会自动合并到宿主,主要内容:
<key>UIBackgroundModes</key>
<array>
<string>location</string>
<string>audio</string>
<string>fetch</string>
<string>processing</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>uni.ly028.keeplive.refresh</string>
<string>uni.ly028.keeplive.upload</string>
</array>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>保活需要在后台持续获取位置更新</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>需要定位权限以支持后台保活</string>
定位用途文案请在自己项目的 manifest 中改成符合业务的描述;离线打包需手动把这些键并入宿主 Info.plist(详见 专栏第 13 节)。
定位权限请使用 requestAlwaysAuthorization,仅 requestWhenInUseAuthorization 无法在后台持续获取位置。
⚠️ App Store 审核提示:
- 后台定位功能需要在审核时说明合理的使用理由
- 音频保活建议在 App 中有实际的音频播放上下文
- BGTaskScheduler 需声明使用目的
HarmonyOS
插件已自动声明以下权限(在 module.json5 中):
ohos.permission.KEEP_BACKGROUND_RUNNING— 后台运行ohos.permission.RUNNING_LOCK— CPU 唤醒锁ohos.permission.LOCATION— 后台定位(可选,使用 startLocation 时需授予)ohos.permission.LOCATION_IN_BACKGROUND— 后台持续定位ohos.permission.INTERNET/GET_NETWORK_INFO— 后台常驻定位上报(1.4.0)ohos.permission.PUBLISH_AGENT_REMINDER— 上报被杀中断提醒(1.4.0)
⚠️ 宿主必配:使用后台定位(
register长时任务、startLocation、后台常驻上报)必须在项目根目录harmony-configs/entry/src/main/module.json5中为 EntryAbility 声明"backgroundModes": ["location"](同时用音频写["location", "audioPlayback"])。插件无法代配,完整文件与步骤见 鸿蒙宿主必配 harmony-configs。
注意事项
Android 版本兼容
| API 级别 | 关键处理 |
|---|---|
| 21-22 | 传统 startService,无通知渠道 |
| 23-25 | 电池优化白名单检查 + 跳转设置引导 |
| 26-30 | NotificationChannel + startForegroundService |
| 31-32 | foregroundServiceType="specialUse",后台启动限制 |
| 33 | POST_NOTIFICATIONS 运行时权限检查 + 动态引导 |
| 34+ | startForeground 三参数签名 + ServiceInfo |
Android 厂商适配
- 不同手机厂商(华为、小米、OPPO、vivo、三星、中兴、传音、Google 等)的后台管理策略不同
- 调用
getOemBatteryGuidance()获取结构化引导文案,在前端自定义弹窗或设置页展示 register({ debug: true })时仍会将相同引导输出到 UTS 日志(debug: false时静默)- 建议引导用户将 App 加入厂商的「受保护应用」或「自启动」白名单
OemBatteryGuidance 字段:brand(归一化 key,如 xiaomi)、manufacturer(展示名)、guideContent(多行引导正文)、rawManufacturer / rawBrand(原始设备信息)。
iOS 限制
- iOS 系统对后台活动有严格限制,保活效果不如 Android
- 定位保活会持续消耗电量,建议仅在对定位实时性要求高的场景使用
- 音频保活建议在合适的时机启动,避免影响用户体验
- 通知使用说明:
updateNotificationContent()发布的是本地通知,非 Android 常驻通知栏。register()时会自动弹出通知权限请求弹窗,请选择「允许」- 通知在 App 退到后台或以任何方式在前台时都会显示横幅
- iOS 通知中心会保留最近的通知记录,下滑可查看历史
- 如果没看到通知,请检查:设置 → 通知 → 本应用 → 允许通知
- 进程被杀后的恢复:
onLocation是 JS 闭包,进程被杀即亡,无法由原生自动重挂——前端冷启动后需重调restoreIOSActivities(cb)(或startLocation)挂回回调。定位/音频/中断配置由register()从 UserDefaults 自动恢复,前端不需要保存任何状态(见上文「iOS 恢复与自愈」)
HarmonyOS 限制
- 后台持续运行依赖长时任务(location),宿主必须配置 harmony-configs;未配置时退化为一次短时任务(约 3 分钟)
- 后台定位需要用户在系统设置中授予位置权限(
始终允许) - 无声音频保活和 WorkScheduler 周期拉活功能需 SDK 版本支持,当前标记为暂不可用
- 鸿蒙三方应用收不到开机广播,无开机自启;进程被杀后需用户重新打开 App
- 鸿蒙 NEXT 版本可能有 API 变更,请关注适配
HarmonyOS 旧 API 行为变化(1.4.0)
| API | 变化 |
|---|---|
register |
改为长时任务 LOCATION(自带系统常驻通知,title / content 不再用于常驻通知,只持久化供 restore);长时任务失败时退化为一次短时任务,不再循环续申请 |
checkLocationPermission |
由固定「已授权」改为真实判断:位置服务未开启 / 已拒绝 / 仅使用期间 / 始终允许 / 未知(与 iOS 文案一致) |
checkNotificationPermission |
改为只读检测(原实现会弹系统授权框) |
openNotificationSettings |
未授权时先弹系统授权框,已授权时跳应用详情页 |
startLocation |
期间持有长时任务;前台定位授权后每个进程最多引导一次「始终允许」设置弹窗 |
restoreKeepAlive |
进程重启后可用上次的配置恢复 |
getCapabilities |
补齐字段;bootCompleted 按原值仍为 true,但鸿蒙实际无开机自启 |
updateNotificationContent |
发布普通通知(长时任务通知内容由系统管理,不可改) |
getKeepAliveReviveLog |
审计日志持久化,进程重启后可读回(最多 40 条) |
getOemBatteryGuidance |
厂商 / 品牌取自 deviceInfo 真实值 |
startPeriodicTask / startMusic / startLongRunningTask |
仍为空实现,返回值不变 |
常见问题
Q:unregister() 和 unregisterAndClear() 有什么区别?
A: 仅停止保活、释放资源,但保留注册配置到 SharedPreferences。如果用户重启手机,BootReceiver 会自动恢复前台服务。 在停止保活的同时清除所有保存的配置,重启后不会自动恢复。
Q:保活一定能防止 App 被杀吗?
A:不能保证 100% 保活。保活是提升 App 进程优先级,降低被系统杀死的概率。极端情况下(内存不足、厂商强杀)仍可能被杀死。
Q:注册后通知栏没有常驻通知?
A:请检查:① 是否使用自定义调试基座/正式包(标准基座不生效);② Android 13+ 是否已开启通知权限(可调用 checkNotificationPermission() 检测);③ register 参数是否正确。
Q:Android 13+ 通知权限怎么处理?
A:插件提供 checkNotificationPermission() 和 openNotificationSettings() 两个 API,你可以在需要显示通知的时机(如点击「前台服务」按钮时)动态检查权限,未开启时引导用户前往系统设置打开。注册保活本身不拦截权限。
Q:前台服务通知可以隐藏吗?
A:可以。调用 setNotificationVisible(false) 隐藏通知栏常驻通知,此时 WakeLock 持续保活但进程优先级会降低。需要重新显示时调用 setNotificationVisible(true)。register() 不会替你自动关闭通知,显隐由业务侧按需调用。
Q:JobScheduler / 闹钟拉活怎么用?重启还有效吗?
A:先 register(),再 startPeriodicTask(15) 或 startAlarmRevive(15)(间隔不得小于 15 分钟),或 startLocation()。成功后会持久化到 SP,重启手机由 BootReceiver 恢复;App 启动可再调 restoreReviveTasksFromPrefs()。失败时用 getLastPeriodicTaskError() / getLastAlarmReviveError() 查看原因。
Q:Android 12+ 闹钟拉活失败?
A:多为未授予「闹钟与提醒」权限。先 canScheduleExactAlarms() 检查,失败时调用 openExactAlarmSettings() 跳转系统设置。
Q:启动后通知栏没有图标?
A:请确保 register 的 icon 参数传入了有效的资源 ID(如 R.drawable.ic_notification 或应用图标资源)。不传则使用应用图标。
Q:真机调试没有反应?
A:是否使用 自定义调试基座?UTS 原生插件必须在自定义基座或正式包中运行。
Q:耗电情况如何?
A:Android 前台服务是系统级高优先级进程,功耗相对较低。WakeLock 使用 PARTIAL_WAKE_LOCK(CPU 唤醒,屏幕可关闭),正常待机功耗增加约 5%-10%。iOS 定位保活持续使用 GPS,功耗较高,建议仅在必要时启用。
更新日志
许可
点击下载体验
扫码体验

收藏人数:
购买源码授权版(
试用
使用 HBuilder 导入示例项目
赞赏(0)
下载 933
赞赏 0
下载 12770358
赞赏 1959
赞赏
京公网安备:11010802035340号