更新记录

1.4.0(2026-10-13)

  • 新增 三端「后台常驻持续定位上报」:App 退到后台 / 锁屏 / 前端 JS 被回收后,原生继续按间隔采集定位并上传到你的服务器(详见 readme「后台常驻持续定位上报专栏」)
    • 新 API:startBackgroundLocationUploadAsync / stopBackgroundLocationUpload / getBackgroundLocationUploadStatus / getBackgroundLocationUploadRecordsAsync / onBackgroundLocationUploadEvent / offBackgroundLocationUploadEvent
    • 本地离线队列(断网缓存、失败重试、失败区),批量上传与单点实时两种模式
    • 一键授权(位置开关 / 前台 / 后台始终 / 通知),健康体检 healthIssues
    • 拉活自动恢复:配置原生持久化,被杀后经保活拉活 / 开机 / 重启 App 自动恢复上报,无需前端调用
    • 全局事件监听:页面重新打开即可继续收到点位 / 上传结果 / 状态
    • 坐标系 wgs84 / gcj02 / bd09
  • 重要 鸿蒙宿主必须在 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 后:

  1. 确认 manifest.json 已配置正确的 AppID
  2. 制作自定义调试基座 → 运行到自定义基座(真机)
  3. 各平台按 平台配置 章节完成额外配置

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 为单一事实源:

  1. register() 自动恢复:register() 在注册前读取 was_running 标记;若上次被杀前保活在运行,自动从 UserDefaults 恢复定位保活与音频保活(带自愈守卫,已在运行时绝不重复启动)。因此点中断横幅重开与杀进程后点图标重开是同一条路径(都是冷启动 → App 入口自然调 register()),前端无需区分场景。
  2. restoreKeepAlive():被杀前在运行时,用持久化的中断 4 参数重新 register()(register 内部再自动恢复定位/音频)。
  3. 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 已按系统语言翻译,可直接 toast
  • data 为业务 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:

  1. 立即收到 state 快照(reason=subscribed,running=true,带待传 / 失败条数)
  2. 之后持续收到 point / upload 事件,页面即可继续刷新
  3. 不需要、也不应该再调一次 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 等)已由插件自动合并,宿主不必重复声明。

配置步骤:

  1. 在 uni-app 项目根目录新建文件:harmony-configs/entry/src/main/module.json5(DCloud 官方 harmony-configs 机制,该文件会整文件覆盖编译生成的 entry 配置)
  2. 复制下面完整内容(以插件示例工程同路径文件为准),关键是 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"
      }
    ]
  }
}
  1. 如果你的项目已有该文件(比如配置过其他 Ability 属性),只需在 EntryAbility 里加上 "backgroundModes": ["location"],不要整段替换掉自己的配置
  2. 同时使用保活的音频能力时写成 ["location", "audioPlayback"]
  3. 重新运行到鸿蒙 / 重新打包

如何确认生效:

  • 已生效:开始上报后状态栏出现长时任务通知,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)

定位保活说明:

  1. 调用 startLocation() 时,未授权会自动弹出定位权限请求,用户授权后自动开始定位(无需二次调用)。
  2. 传入 title 时会同时请求通知权限(Android 13+),并以该标题在通知栏展示定位保活状态;前台服务会附加 location 类型。
  3. Android 10+:前台定位授予后,插件会内部再申请 ACCESS_BACKGROUND_LOCATION;若系统弹窗无「始终允许」或用户拒绝,可再引导到设置中手动开启(拒绝不阻断定位保活启动)。仅「使用期间」时,息屏长期后台定位可能受限。

开机与拉活任务恢复:

  1. register() 将保活配置写入 SharedPreferences。
  2. 若已调用 startPeriodicTask() / startAlarmRevive() / startLocation() 且成功,对应开关会写入 SP。
  3. 手机重启后 BootReceiver → 恢复定位保活(若已开启)+ 前台服务 + JobScheduler + AlarmManager。定位恢复阶段无 JS 回调;App 再次打开后重调 startLocation 可重挂 onLocation。
  4. 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 列为运行时权限,用户可以在系统设置中开关。如果通知不显示:

  1. 使用 checkNotificationPermission() 检查权限状态
  2. 未授予时调用 openNotificationSettings() 跳转到应用通知设置页
  3. 用户手动开启后,重新注册前台服务即可显示常驻通知

插件采用「按需检查」策略:注册保活时不拦截通知权限,前台服务/通知控制按钮在点击时才动态检查并引导开启。

Android 6+ 电池优化说明:

部分厂商会强制休眠后台应用,即使有前台服务也可能受影响。建议引导用户:

  1. 调用 openBatteryOptimizationSettings() 跳转到电池优化设置
  2. 将本应用设为「不优化」

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,功耗较高,建议仅在必要时启用。


更新日志

见 changelog.md

许可

见 license.md


点击下载体验
扫码体验
扫码体验

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android:FOREGROUND_SERVICE、WAKE_LOCK、RECEIVE_BOOT_COMPLETED、SCHEDULE_EXACT_ALARM;iOS:后台定位权限;HarmonyOS:KEEP_BACKGROUND_RUNNING、NOTIFICATION_USER_INITIATED

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无