更新记录

1.0.0（2026-10-17） 下载此版本

Android 保活：常驻通知 + 唤醒锁 + 息屏定时任务 + 电池白名单/通知权限引导

平台兼容性

uni-app(5.26)

lj-keeplive · Android 后台保活

一行代码启动后台保活。不依赖任何第三方 SDK。

一、功能

适用场景：后台维持长连接、周期性上报、蓝牙通信、推送协同、息屏后的定时同步。

二、平台支持

三、使用前提

1. 必须使用自定义基座

标准基座不含插件的原生内容，运行会完全无效。

• 制作路径：HBuilderX → 运行 → 运行到手机或模拟器 → 制作自定义调试基座
• 手机上已装过旧基座时，先卸载再安装新的

2. 打包方式

只支持云端传统打包，不支持离线打包、不支持安心打包。

四、快速开始

最小用法

// #ifdef APP
import { register, unregister } from '@/uni_modules/lj-keeplive'

register()      // 启动保活
unregister()    // 停止保活
// #endif

完整用法（含权限引导）

// #ifdef APP
import {
  register,
  unregister,
  isRunning,
  getAliveSeconds,
  getTickCount,
  setNotification,
  setSmallIcon,
  setNotificationId,
  setChannel,
  setTimerInterval,
  setWakeLockTimeout,
  setDebug,
  Tick,
  onScreenStateChange,
  isNotificationEnabled,
  requestNotificationPermission,
  isIgnoringBatteryOptimizations,
  requestIgnoreBatteryOptimizations,
  openNotificationSettings,
  openAppSettings
} from '@/uni_modules/lj-keeplive'

// ---- 1. 配置（在 register 之前调用）----
setDebug(true)
setNotification('应用正在后台运行', '保活服务已启动')
setTimerInterval(60)        // 后台定时任务周期（秒），0 表示关闭
setWakeLockTimeout(600)     // 唤醒锁时长（秒），0 表示不使用

// ---- 2. 注册回调（只需注册一次）----
Tick((count) => {
  console.log('定时任务触发，累计次数：', count)
})

onScreenStateChange((screenOn) => {
  console.log(screenOn ? '屏幕已点亮' : '屏幕已熄灭')
})

// ---- 3. 申请通知权限后启动 ----
if (isNotificationEnabled()) {
  start()
} else {
  requestNotificationPermission((granted) => {
    console.log('通知权限申请结果：', granted)
    start()
  })
}

function start() {
  register()
  // 引导加入电池优化白名单
  if (!isIgnoringBatteryOptimizations()) {
    requestIgnoreBatteryOptimizations()
  }
}
// #endif

停止保活

// #ifdef APP
unregister()
// #endif

五、API 文档

5.1 配置项

以下方法建议在 register() 之前调用。

5.2 生命周期

5.3 回调

这两个方法注册的是持续触发的回调，只需注册一次；重复注册会覆盖上一次。

5.4 权限与系统设置

六、默认值一览

七、通知图标

• 插件内置图标：utssdk/app-android/res/drawable/ic_keeplive.xml
• setSmallIcon() 传入的是 drawable 资源名，不带扩展名
• 换成自己的图标：把同名图标文件放到你项目根目录的 nativeResources/android/res/drawable/（或 mipmap/）下即可覆盖，保持资源名一致，无需改代码
• 图标解析顺序：drawable 同名资源 → mipmap 同名资源 → 应用自身图标

八、权限说明

插件会在打包时声明以下 Android 权限：

如何修改：

• 移除电池白名单权限：删除插件内置 AndroidManifest.xml 中对应的 <uses-permission>，并同步删除项目 manifest.json 里 app-plus.distribute.android.permissions 的同名项。注意该权限属于敏感权限，Google Play 上架审核会重点审查，国内应用市场一般不受影响。
• 改前台服务类型：若你的应用具备真实的后台音频播放或数据传输业务，可把 AndroidManifest.xml 中的 android:foregroundServiceType="specialUse" 改为 mediaPlayback / dataSync，并同步替换权限为 FOREGROUND_SERVICE_MEDIA_PLAYBACK / FOREGROUND_SERVICE_DATA_SYNC。注意 Android 15 对 dataSync 有「24 小时内累计 6 小时」的强制停止限制。
• Google Play 上架：specialUse 类型需要在 Play Console 中填写相同用途的使用理由。

九、常见问题

Q1：调用 register() 后毫无反应，通知栏也没有通知？

请确认已使用自定义基座运行。标准基座不含插件的原生内容，制作基座后在安装前先卸载旧基座。

Q2：服务已启动，但通知栏看不到常驻通知？

用 isNotificationEnabled() 检查、requestNotificationPermission() 申请通知权限。也可检查用户是否单独关闭了该通知渠道。

Q3：息屏一段时间后定时任务不再触发？

用 getTickCount() 判断是否还在增长。若不再增长，依次检查：

1. setWakeLockTimeout() 是否为 0 或负数
2. 是否已加入电池优化白名单（isIgnoringBatteryOptimizations()）
3. 系统设置里是否允许「自启动」「后台运行」，是否把应用锁定在最近任务列表
4. 是否被厂商的「省电策略」「应用智能省电」限制

Q4：改了通知标题，为什么通知里没变？

文案变更后需要重新调用一次 register()。若要改铃声、震动等渠道属性，必须通过 setChannel() 换一个新的 channelId。

Q5：unregister() 之后可以立刻 register() 吗？

可以。

Q6：能保证 App 永不被杀吗？

不能。保活只能提升存活率，无法对抗用户的主动结束、系统资源紧张与厂商 ROM 策略。

十、已知限制

• 仅支持 Android，iOS / 鸿蒙 / H5 / 小程序均不支持。
• 仅支持云端传统打包，不支持离线打包、安心打包。
• 应用被系统回收后重新启动保活时，会回退到默认配置，请在启动时重新下发配置。
• 定时任务的实际触发间隔受系统调度影响，建议周期不小于 30 秒。
• 唤醒锁会带来额外耗电，请按业务需要设置合理的 setWakeLockTimeout() 值。

十一、隐私声明

• 不采集、不存储、不上传任何用户数据
• 不含任何广告 SDK
• 不发起任何网络请求
• 仅使用上文列出的 Android 系统权限，用途均已在权限表中说明

十二、更新日志

1.0.0

• 首次发布。
• 支持前台服务 + 常驻通知保活。
• 支持唤醒锁与到期自动续期。
• 支持息屏 / 亮屏监听与屏幕状态回调。
• 支持后台定时任务。
• 提供通知权限申请、电池优化白名单引导、系统设置页跳转。