安装与配置
安装 HAC 和插件，完成应用配置、网络权限、设备兼容性、扫码广播、升级回退和首次运行验证。
本部分用于把活字格应用部署到 HAC 和 PDA。先准备应用、插件和设备，再安装 HAC、发布应用、生成并导入配置码，最后用一个最小业务流程验证登录、网络和设备能力。
使用前提
- Android 版本不低于
8.0； - 运行内存建议不低于
2GB； - 活字格应用已发布到设备可访问的服务器；
- 设计器中已安装需要的 PDA / Android 交互命令插件；
- 目标 PDA 的 WebView、系统权限、网络和硬件能力已验证；
- 已确认目标设备型号、扫描方式、网络环境和现场操作账号；
- 已准备应用 URL、配置二维码接收方式以及测试用的账号和业务数据。
这些是当前文档的验证基线，不替代具体设备和版本的厂商要求。
部署前准备
| 角色 | 准备内容 | 完成标准 |
|---|---|---|
| 活字格开发人员 | 页面、PDA / Android 交互命令插件和应用发布权限 | 应用已发布，记录应用 URL、插件版本和发布时间 |
| IT 运维人员 | HAC 安装包、目标 PDA、网络和厂商设备配置工具 | PDA 已安装 HAC，可以联网，扫描头、UHF / RFID 或其他硬件已开启 |
| 最终用户 | 现场操作账号、测试任务和业务操作要求 | 能登录 HAC，完成实际业务流程，并确认页面和设备操作符合现场要求 |
部署前应区分测试环境和生产环境。应用 URL、配置二维码和账号信息不要混用；同一批 PDA 应记录设备型号和目标环境，便于后续升级和问题追踪。
下载地址
- HAC 应用：下载地址；
- HAC 插件：插件市场；
- 配置码生成器：一键生成和导出配置码。
首次部署
准备应用、插件、设备和测试账号
-> 在设计器中安装交互命令插件
-> 配置页面并发布活字格应用
-> 安装 HAC 并记录版本
-> 生成应用配置二维码
-> 在 HAC 中导入配置并确认应用地址
-> 按项目要求配置 ActionBar、菜单和扫描头参数
-> 配置权限、网络和设备硬件
-> 验证登录、目标设备能力和关键页面
配置完成后，先确认应用能打开并登录，再逐项验证设备能力。不要在设备能力尚未确认时直接进入连续作业。
安装 HAC
- 在目标设备上确认 Android 版本不低于
8.0，并预留足够的存储空间； - 从下载地址获取与项目要求匹配的 HAC 安装包；
- 在设备上安装 APK。若系统阻止安装未知来源应用，按企业设备管理策略允许当前安装来源，或改用企业应用分发 / MDM 安装；
- 启动 HAC，记录 HAC 版本，并进入配置入口；
- 首次扫描配置二维码时按提示授予相机权限。相机权限只用于二维码扫描或页面拍摄，其他能力按实际使用场景授权。
不要直接卸载旧版本
升级或重装前先确认配置和离线记录是否需要保留。卸载应用可能清除设备本地配置、登录状态或离线数据；生产设备应先完成数据补传，并保留当前版本和配置记录。
安装插件并发布应用
- 在活字格设计器中安装项目实际需要的 PDA / Android 交互命令插件；
- 在页面中配置对应命令，并为成功、失败、权限拒绝和设备不可用定义页面处理；
- 发布活字格应用，确认发布后的应用 URL 能在目标 PDA 网络中访问；
- 记录设计器版本、插件版本、应用版本、应用 URL 和发布时间。
插件新增、删除或升级后，应重新发布应用，并在目标 HAC 中重新验证相关命令。未使用的设备能力不必安装对应插件，也不应在页面中显示无效入口。
生成应用配置二维码
打开配置码生成器，至少填写以下内容：
- 活字格应用 URL；
- HAC 所需的容器配置；
- 项目实际使用的扫描头、UHF / RFID 或其他设备参数（如需要）。
应用 URL 必须能在目标 PDA 上访问。生产环境优先使用受 Android 和 WebView 信任的 https 地址；如果使用内网地址、HTTP 或自签名证书，应先在目标设备上验证网络和证书策略。
生成二维码后，记录二维码对应的环境、应用 URL、生成时间、配置版本和目标设备。二维码只应在受控范围内传递，不要把账号密码、长期令牌或其他敏感信息写入配置。
在 HAC 中导入配置
- 打开 HAC 的配置入口；
- 选择扫描配置二维码，按提示授予相机权限；
- 扫描配置二维码，检查应用 URL 和关键容器参数；
- 保存配置，等待 HAC 重新加载应用；
- 确认应用页面打开、登录页可用，并能显示正确的环境和应用名称；
- 关闭并重新启动 HAC，确认配置仍然保留。
如果二维码无法识别，先提高屏幕亮度、调整扫码距离并确认相机权限；如果扫描成功但页面打不开，优先检查应用 URL、DNS、网络、证书和 WebView。配置错误时不要继续测试业务，重新生成正确二维码后再导入。
网络与服务器检查
| 检查项 | 验证内容 | 通过标准 |
|---|---|---|
| 应用地址 | 在 PDA 的 HAC 中打开配置的应用 URL | 页面能打开，不出现 DNS、连接超时或证书错误 |
| DNS / VPN / 代理 | 确认设备使用的网络、内网、VPN 和代理策略 | 设备在实际现场网络中能访问应用和业务接口 |
| HTTPS / 证书 | 检查服务器证书链、域名和有效期 | Android 和 WebView 信任该证书，页面资源和接口均能加载 |
| 登录与权限 | 使用测试账号登录，进入目标业务页面 | 账号、角色和页面权限与现场角色一致 |
| 文件与接口 | 测试页面实际使用的查询、提交、上传或下载接口 | 接口返回正常，失败时页面显示原因和重试入口 |
| 弱网与断网 | 关闭网络或切换弱网后执行一次非破坏性操作 | 页面显示网络状态，不丢失必要输入；业务支持离线时可暂存和补传 |
如果应用部署在内网，不能只在电脑浏览器中验证。必须使用目标 PDA 的实际网络测试；必要时记录 DNS、代理、VPN、证书和服务器地址类型。
设备与版本检查
| 检查项 | 验证内容 | 通过标准 |
|---|---|---|
| Android | 系统版本、设备型号和可用存储空间 | Android 版本不低于 8.0，设备满足项目和厂商要求 |
| HAC | HAC 版本和应用包安装状态 | HAC 能启动，版本与项目验证记录一致 |
| WebView | Android System WebView / 厂商 WebView 版本 | 目标页面能正常加载，脚本、文件和接口行为符合项目要求 |
| 插件 | 设计器和发布应用使用的 PDA / Android 交互命令插件版本 | 页面实际调用的命令在目标 HAC 中可用 |
| 硬件 | 扫描头、UHF / RFID、NFC、BLE、摄像头和物理按键 | 设备系统或厂商程序已开启对应硬件和服务 |
权限检查
按页面实际使用的能力授权，不要为了安装 HAC 一次性授予所有权限。权限名称和申请时机可能因 Android 版本、设备厂商和应用 targetSdk 不同而变化，应以目标设备系统提示和对应功能页为准。
| 能力 | 需要检查的权限或系统开关 | 验收与恢复 |
|---|---|---|
| 二维码扫码 / 拍照 / 录像 | 相机权限，设备摄像头可用 | 能打开相机并完成一次采集；拒绝权限时显示授权或备用入口 |
| 录音 | 麦克风权限，设备未被其他应用占用 | 能完成一次录音；拒绝时页面不能无响应 |
| 定位 | 定位权限和系统定位开关 | 能返回定位结果；关闭定位时提示开启并允许重试 |
| BLE | 蓝牙开关，以及目标 Android 版本要求的扫描 / 连接权限 | 能发现并连接目标设备；权限不足时说明原因 |
| NFC | NFC 系统开关和设备 NFC 硬件 | 能读取测试标签；不支持时隐藏入口或提供替代方式 |
| 文件 / 媒体 | 设备版本对应的文件或媒体访问权限 | 能选择、读取和上传测试文件；权限拒绝时保留页面状态 |
| 物理按键 / 扫描广播 | 厂商扫描服务、广播 / Intent 配置 | 按键或广播能触发页面；离开页面后监听已停止 |
Android 12 及以上版本的蓝牙权限名称可能与旧版本不同；Android 10 及以上版本的文件访问策略也可能不同。遇到差异时应记录 Android、HAC、WebView 和插件版本，并按目标机型单独验证。
扫码广播配置
扫描头或 UHF 通常需要在设备厂商工具中开启“广播”或 Intent 模式，并配置 Action 和 Extra key。HAC 中的配置必须和设备侧保持一致。
配置和验证步骤：
- 确认 PDA 厂商、型号、Android 版本和扫描服务版本；
- 在设备厂商工具中选择广播 /
Intent输出模式； - 配置 Action、Extra key、码值前后缀、回车或其他分隔符；
- 在 HAC 或应用配置中填写相同参数；
- 打开扫码测试页，使用物理扫描键或 UHF 读卡器读取测试码；
- 确认页面收到完整码值，并分别验证成功、重复、无效和取消等结果。
页面需要连续扫码时，应确认进入页面后监听已启动，离开页面、打开弹窗或任务完成后监听已停止。扫码配置只适用于实际使用扫描头或 UHF 的项目；仅使用相机扫码的项目可以跳过广播配置。
| 厂商 | 广播 Action | Extra key |
|---|---|---|
| 东大集成（Q9 等老产品，扫描头） | com.android.server.scan | scannerdata |
| 东大集成（小码哥等新产品，扫描头 / UHF） | com.android.server.scannerservice.broadcast | scannerdata |
| 亿博讯（扫描头） | android.intent.ACTION_DECODE_DATA | barcode_string |
| 亿博讯（UHF） | com.ubx.scan.rfid | rfid_data |
| 盈达 iData | android.intent.action.SCANRESULT | value |
| 成为（扫描头） | com.scanner.broadcast | data |
| 成为（UHF） | com.rscja.scanner.action.scanner.RFID | data |
| 商米 | com.sunmi.scanner.ACTION_DATA_CODE_RECEIVED | data |
| 斑马 / Zebra | 参考厂商配置教程 | 参考厂商配置教程 |
先验证配置
同一厂商的不同型号和系统版本可能使用不同默认值。现场配置前，先用厂商工具确认 Action、Extra key、扫码模式和 UHF 模式，再进入 HAC 验证。
兼容设备基线
| 设备型号 | 基础功能 | 照片上传 | 文件上传 | 摄像头扫码 | 扫描头扫码 | RFID |
|---|---|---|---|---|---|---|
| 东大集成 Q9 / Q9C / Q7 / 小码哥A / 小码哥5G / UTOUCH / UTOUCH2 | √ | √ | √ | √ | √ | UTOUCH / UTOUCH2 |
| 亿博讯 DT40 / DT50 / DT50U（Android 11） | √ | √ | √ | √ | √ | DT50U |
| 盈达 P50 / iData50（Android 9） | √ | √ | √ | √ | √ | |
| 成为 C72（Android 11） | √ | √ | √ | √ | √ | √ |
蓝牙打印机验证：
| 设备型号 | 功能验证 |
|---|---|
| 德佟 DP30 | √ |
| 佳博 GP-M322 | √ |
兼容性表是当前验证记录，不代表所有型号、系统版本或厂商配置都具备相同能力。
建议为每次验证保留以下记录：
| 记录项 | 示例或说明 |
|---|---|
| 设备型号 | 厂商和完整型号 |
| Android 版本 | 例如 11 |
| HAC 版本 | 安装包版本或应用信息中的版本 |
| WebView 版本 | Android System WebView 或厂商 WebView 版本 |
| 插件版本 | 设计器安装并随应用发布的插件版本 |
| 扫描配置 | Action、Extra key、扫描模式和前后缀 |
| 网络环境 | Wi-Fi、移动网络、内网、VPN 或代理 |
| 验证日期与结果 | 通过、失败、限制及问题单编号 |
升级、回退与配置保留
升级 HAC 或交互命令插件前：
- 确认生产设备没有待补传的离线记录，或已经按项目方案完成导出和补传；
- 保存当前 HAC 版本、应用版本、插件版本、配置二维码和设备参数；
- 先在一台测试 PDA 上覆盖安装新版本，并执行首次运行验收；
- 验证通过后再分批升级生产设备，保留旧版本安装包和回退记录。
如果新版本出现兼容性问题，优先回退到已验证的 HAC / 插件组合。只有在确认本地配置和离线数据已处理后，才考虑卸载重装；卸载可能清除本地配置、登录状态或离线数据。回退或重新导入配置后，必须重新验证应用地址、登录、扫码和项目实际使用的设备能力。
常见安装与配置问题
| 现象 | 优先检查 | 恢复方式 |
|---|---|---|
| APK 无法安装 | Android 版本、存储空间、安装来源限制、签名冲突 | 使用匹配版本安装包，按设备管理策略允许安装来源；不要随意卸载含有离线数据的旧版本 |
| HAC 能启动但页面白屏 | 应用 URL、DNS、VPN / 代理、证书、WebView | 在目标 PDA 网络中打开地址，记录 WebView 版本；仍失败时使用调试 |
| 配置二维码无法识别 | 相机权限、亮度、距离、二维码清晰度 | 授权相机，调整显示或打印尺寸；重新生成并导入配置码 |
| 扫码成功但应用打不开 | 配置中的 URL 或环境错误、服务器不可达 | 重新核对配置码和环境，确认目标设备可以访问服务器 |
| 页面提示权限不足 | Android 权限或系统开关未开启 | 到系统设置授权对应能力，返回页面后重试；仍失败时记录版本和权限状态 |
| 物理扫码键无反应 | 厂商扫描服务、Action、Extra key、监听状态 | 对照设备配置重新核对，重启扫描服务或重新进入扫码测试页 |
| 相机、定位、BLE 或 NFC 无结果 | 硬件未开启、权限不足、设备不支持或被其他应用占用 | 检查系统开关和权限，确认设备能力基线，提供页面备用操作 |
| 登录或提交超时 | 网络、证书、服务器接口、账号权限 | 先确认页面是否已保存输入，避免重复提交；检查调试和日志 |
反馈问题时至少提供设备型号、Android、HAC、WebView、插件版本，应用 URL 类型，复现时间、步骤、网络环境和相关日志。不要在工单或日志中暴露账号密码、配置二维码或长期令牌。
首次运行验收
- 已记录设备型号、Android、HAC、WebView、插件版本和目标环境；
- HAC 重启后仍能加载正确的应用 URL，页面可以完成登录；
- 页面加载后能显示当前任务、网络状态和关键操作入口；
- 项目实际使用的每种设备能力都完成一次真机验证，并能显示成功结果；
- 扫码项目已验证成功、重复、无效和取消等结果，页面有对应反馈；
- 拒绝相机、定位、蓝牙或其他权限后，页面能提示恢复方式或提供备用操作；
- 切换后台、刷新页面或重新进入页面后，扫码、广播、BLE 和物理按键监听没有重复触发；
- 项目支持离线时，断网或提交超时后必要数据仍然保留，并可按方案重试或补传；
- 关键业务提交成功后，页面状态和服务端数据一致，重复点击不会生成重复业务记录。