更新记录

1.0.0（2026-04-23）

平台兼容性

uni-app(4.87)

uni-app x(4.87)

IM 全方位增强保活插件 (im-keepalive)

本插件是专为 uni-app / uni-app x 开发的高强度保活利器。它通过多进程协作与系统级调度，显著提高应用在熄屏、锁屏状态下的后台存活率，解决 WebSocket 断连及推送接收延迟。

快速上手三步走

1. 静态资源准备

保活策略中的“静默音频”必须引用原生 Resource：

• 在 uni_modules/im-keepalive/utssdk/app-android/res/raw/ 目录下放入一个无声 MP3 文件，命名为 silent.mp3。
• 路径示例：src/uni_modules/im-keepalive/utssdk/app-android/res/raw/silent.mp3

2. 基座制作 (必须)

由于插件涉及 Android 原生 Service 的注册与多进程配置，普通运行无法生效：

• 点击 HBuilderX 顶部菜单：运行 -> 运行到手机或模拟器 -> 制作自定义调试基座。
• 打包完成后，勾选 使用自定义调试基座运行 再次启动。

3. 代码集成 (App.vue)

在 App.vue 中引入并初始化。以下代码包含了 Android 13 权限合规处理：

import { 
  startKeepAlive, 
  isIgnoringBatteryOptimizations, 
  requestIgnoreBatteryOptimizations 
} from "@/uni_modules/im-keepalive"

onLaunch(() => {
  // #ifdef APP-PLUS || APP-ANDROID
  initKeepAlive()
  // #endif
})

function initKeepAlive() {
  setTimeout(() => {
    try {
      // Android 13+ 通知权限申请
      const sysInfo = uni.getSystemInfoSync()
      if (sysInfo.platform === 'android' && parseInt(sysInfo.osVersion) >= 13) {
        plus.android.requestPermissions(['android.permission.POST_NOTIFICATIONS'], (e) => {
          if (e.granted && e.granted.length > 0) console.log("通知权限已就绪")
        })
      }

      // 启动保活 (推荐采用 30 秒心跳的均衡模式)
      startKeepAlive({
        debug: true,
        foreground: { enable: true, title: "IM消息服务", content: "持续接收中" },
        remote: { enable: true, interval: 30000 },
        enableWakeLock: true,
        enableSilentAudio: true
      })

      // 引导开启电池白名单
      if (!isIgnoringBatteryOptimizations()) {
        uni.showModal({
          title: '保活提醒',
          content: '请允许应用后台运行以确保消息不延迟。',
          confirmText: '去设置',
          success: (res) => {
            if (res.confirm) requestIgnoreBatteryOptimizations()
          }
        })
      }
    } catch (e) { console.error("保活启动失败:", e) }
  }, 1000)
}

核心策略 (V2.0 模块化版)

功耗平衡与最佳实践 (重要)

[!IMPORTANT] 保活强度与功耗（省电）是一对矛盾。请根据业务场景选择最合理的配置：

1. 建议配置（平衡模式）

如果您主要希望 IM 在后台不掉线，且不希望用户因“耗电快”而投诉：

• remote.interval: 建议设置为 30000 (30秒) 至 60000 (1分钟)。过快的心跳（如 5s）会由于频繁唤醒 CPU 导致功耗陡增。
• enableWakeLock: 开启。
• enableSilentAudio: 开启（插件会自动在亮屏时停止，仅在灭屏时激活，最大程度平衡功耗）。

2. 强力模式（最高保活）

• remote.interval: 设置为 10000 (10秒)。
• 这种逻辑下，应用几乎无法进入深度睡眠（Deep Sleep），耗电量会增加，请在必要的业务时段开启。

权限说明 (Android 13+ 必看)

1. 通知权限： Android 13 (API 33) 及更新版本，必须申请 POST_NOTIFICATIONS 权限。若用户未授权，前台通知将不可见，部分机型的保活强度会因此大幅下降。
2. 电池白名单： 这是国产手机保活的关键。调用 requestIgnoreBatteryOptimizations() 引导用户开启。

API 说明

开发者诊断建议

如果在 HBuilderX 控制台中看不到通知或保活失效，请观察过滤标签为 [IM-KeepAlive] 的日志：

• 🔍 [通知权限状态] 全局开关: OFF：表示用户没给该应用通知权限。
• 🔍 [通知权限状态] 频道权重: 0：表示虽然总开关开了，但该具体的保活通知频道被用户手动关闭了。
• 💓 心跳监测 (:main -> :remote)：表示双进程由于心跳活跃，正在互相监视。

静态资源准备

请确保以下文件存在，否则“静默音频”策略将无法正常启动： src/uni_modules/im-keepalive/utssdk/app-android/res/raw/silent.mp3