bBeng-HeartRate-4.66-pad/KIOSK_SETUP_GUIDE.md

Kiosk 模式自动启动配置指南

📋 概述

本项目已配置为在启动时自动启用 Kiosk 模式，无需通过 JS 调用。包括以下功能：

• ✅ 自动禁用锁屏
• ✅ 屏幕常亮
• ✅ 全屏沉浸式
• ✅ LockTask 模式（防止退出应用）
• ✅ 五指长按 5 秒 + 密码 (9527) 可退出

🛠️ 已完成的配置

1. 自定义 Application 类

• 文件：app/src/main/java/com/YuyeTech/HeartRate/MyApplication.java
• 功能：
  • 自动注册 Activity 生命周期监听
  • 在 Activity 创建时自动调用 KioskHelper.disableLockScreen()
  • 自动绑定 KioskManager

2. AndroidManifest.xml 配置

• 已将 Application 改为 com.YuyeTech.HeartRate.MyApplication

• 已添加必要权限：

  <uses-permission android:name="android.permission.DISABLE_KEYGUARD" />
  <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
  <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  

• 已注册 Device Admin Receiver

• 已注册开机启动 Receiver

3. KioskHelper 辅助类

• 文件：app/src/main/java/com/YuyeTech/HeartRate/KioskHelper.java
• 提供静态方法：
  • disableLockScreen(Activity) - 禁用锁屏
  • keepScreenOn(Activity) - 屏幕常亮
  • enableLockScreen(Activity) - 恢复锁屏

4. device_admin.xml

• 文件：app/src/main/res/xml/device_admin.xml
• 定义 Device Admin 策略

📱 部署步骤

第一步：编译 APK

./gradlew assembleRelease

第二步：设置为 Device Owner（必须）

⚠️ 重要：只有设置为 Device Owner 后，才能完全禁用锁屏和使用 LockTask 模式。

方法 1：使用 ADB 命令（推荐）

1. 确保设备没有添加 Google 账号（恢复出厂设置）

2. 安装 APK：

   adb install app-release.apk
   

3. 设置为 Device Owner：

   adb shell dpm set-device-owner com.YuyeTech.HeartRate/com.ble.mylockview.admin.KioskDeviceAdminReceiver
   

方法 2：使用 NFC 批量配置

1. 准备 NFC 配置文件
2. 在设备初始化时通过 NFC 传输配置

方法 3：使用 QR Code（Android 7.0+）

1. 在设备初始化设置界面，连续点击 6 次欢迎屏幕
2. 扫描包含配置信息的二维码

第三步：验证 Device Owner 状态

adb shell dumpsys device_policy | grep "Device Owner"

如果显示您的应用包名，说明设置成功。

🎮 运行时行为

正常启动流程

1. 应用启动 → MyApplication.onCreate() 执行
2. PandoraEntry Activity 创建
3. 自动调用 KioskHelper.disableLockScreen()
4. 自动调用 KioskManager.attach()
5. 进入 Kiosk 模式

调试模式 vs 生产模式

• Debug 模式 (BuildConfig.DEBUG = true)：

  • 不强制 Device Owner
  • 允许随时退出
  • 日志详细

• Release 模式 (BuildConfig.DEBUG = false)：

  • 必须是 Device Owner 才生效
  • 需要五指长按 5 秒 + 密码才能退出
  • 日志简化

🚪 退出 Kiosk 模式

用户退出（运维人员）

1. 五指同时按住屏幕 5 秒
2. 弹出密码输入框
3. 输入管理员密码：9527
4. 点击"解锁"

开发者退出

在 Debug 模式下，可以直接使用 ADB：

adb shell am task lock stop

🔧 自定义配置

修改管理员密码

编辑 myLockView/src/main/java/com/ble/mylockview/admin/KioskManager.java:

private static final String ADMIN_PASSWORD = "您的密码";

修改逃生门触发条件

编辑 KioskManager.java:

private static final int ADMIN_FINGER_COUNT = 5;      // 手指数量
private static final long ADMIN_HOLD_TIME = 5000;     // 长按时间（毫秒）

禁用开机自启动

在 AndroidManifest.xml 中移除或禁用 BootReceiver：

<receiver
    android:name="com.ble.mylockview.boot.BootReceiver"
    android:enabled="false"  <!-- 改为 false -->
    ...>

🐛 故障排查

问题 1：锁屏仍然出现

原因：未设置为 Device Owner 解决：按照"第二步"设置 Device Owner

问题 2：无法设置 Device Owner

错误：Not allowed to set the device owner... 解决：

1. 恢复出厂设置
2. 移除所有账号（包括 Google 账号）
3. 不要在初始设置中添加账号
4. 重新执行 dpm set-device-owner 命令

问题 3：应用卡死无法退出

解决：

1. 尝试五指长按 5 秒 + 密码 9527

2. 如果失败，使用 ADB：

   adb shell am force-stop com.YuyeTech.HeartRate
   

3. 或者移除 Device Owner：

   adb shell dpm remove-active-admin com.YuyeTech.HeartRate/com.ble.mylockview.admin.KioskDeviceAdminReceiver
   

问题 4：日志显示 "⚠️ 不是 Device Owner"

说明：应用可以正常运行，但 Kiosk 功能有限 解决：如需完整 Kiosk 功能，必须设置为 Device Owner

📝 代码集成说明

如果需要在其他地方使用

方式 1：通过 KioskHelper（推荐）

// 在任何 Activity 中
public class MyActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        // 禁用锁屏（必须在 setContentView 之前）
        KioskHelper.disableLockScreen(this);
        KioskHelper.keepScreenOn(this);
        
        setContentView(R.layout.activity_main);
    }
}

方式 2：通过 KioskManager

// 在 Activity 生命周期中
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    KioskManager.attach(this);
}

@Override
protected void onResume() {
    super.onResume();
    KioskManager.onResume();
}

@Override
protected void onPause() {
    super.onPause();
    KioskManager.onPause();
}

@Override
protected void onDestroy() {
    super.onDestroy();
    KioskManager.onDestroy();
}

🔒 安全建议

1. 生产环境：

   • 将 ADMIN_PASSWORD 改为强密码
   • 考虑将密码存储在加密的 SharedPreferences 中
   • 定期更换管理员密码

2. 发布前检查：

   • 确认 BuildConfig.DEBUG = false
   • 测试五指逃生门是否正常工作
   • 验证 Device Owner 设置流程

3. 备份方案：

   • 保留 ADB 调试通道（至少在测试阶段）
   • 准备物理按键组合退出方案
   • 文档化管理员密码

📞 技术支持

如有问题，请检查日志：

adb logcat | grep -E "KioskManager|MyApplication|KioskHelper"

关键日志标签：

• KioskManager - Kiosk 核心功能
• MyApplication - 应用初始化
• KioskHelper - 锁屏控制
• BootLauncher - 开机启动

---

最后更新：2026-01-22 版本：1.0