APP 交互
HAC 中应用原生页、设备信息、PDF、电话、震动、提示音和广播命令的使用建议。
适用场景
APP 交互命令用于让活字格页面在 HAC 中调用部分 Android 原生能力，例如打开容器配置页、读取 APP / 设备信息、预览 PDF、拨打电话、震动、播放提示音、发送和接收广播。
这些命令通常会离开当前 Web 页面上下文、调用系统界面或监听外部事件。使用前要明确用户会看到什么、当前业务状态如何保存、失败后如何恢复。
使用前提
- 应用运行在
HAC中； - 已安装 PDA / Android 交互命令插件；
- 已确认 HAC、Android 系统、PDA 型号和厂商程序支持对应能力；
- 设备所需的电话、文件、通知、蓝牙或其他系统权限已经处理；
- 页面能识别普通浏览器环境并隐藏或禁用相关入口；
- 涉及广播时，Action、Type、Uri、Extra 来自厂商或目标 APP 文档；
- 进入原生页面、拨打电话或关闭 APP 前，页面已保存需要保留的业务状态。
命令速查
| 能力 | 命令 | 类型 | 输入 / 输出 |
|---|---|---|---|
| 容器页面 | 打开APP的内置页面 | 普通 | 目标页面：配置或快速设置 |
| 环境信息 | 读取APP信息 | 同步或异步，按插件实现为准 | 输出版本号和包名 |
| 环境信息 | 读取APP信息到单元格 | 同步或异步，按插件实现为准 | 输出到指定单元格 |
| 环境信息 | 读取设备唯一标识 | 同步或异步，按插件实现为准 | 输出 SSAID / Android ID |
| 环境信息 | 读取极光推送RegId | 同步或异步，按插件实现为准 | 输出 RegId |
| APP 控制 | 强制关闭APP | 普通 | 无；立即关闭当前 APP |
| 文件和电话 | 预览PDF文件 | 异步 | URL、文件名、密码 |
| 文件和电话 | 拨打电话 | 普通 | 电话号码 |
| 反馈 | 震动提醒 | 普通 | 持续时间（秒） |
| 反馈 | 播放提示音 | 普通 | 声音类型 |
| 广播 | 发送广播 | 异步 | Action、Type、Uri、Extra |
| 广播 | 开始接收广播 | 异步 | Action；返回监听器注册 ID 和 Extra JSON |
| 广播 | 停止监听广播 | 普通 | 监听器注册 ID |
推荐流程
读取环境并判断能力：
执行【读取APP信息】
-> 如果版本号和包名为 N/A：提示不在 HAC 中
-> 如果读取成功：继续调用设备能力
-> 提交问题或业务记录时保存 APP 版本、包名和设备标识PDF 预览：
用户点击“查看 PDF”
-> 页面确认 PDF 地址、文件名和密码
-> 执行【预览PDF文件】
-> APP 下载 PDF 并打开内置预览页面
-> 用户查看或通过系统能力打印广播监听：
进入需要监听的页面
-> 执行【开始接收广播】
-> 保存监听器注册 ID
-> 接收广播回调
-> 解析 Extra JSON
-> 按业务规则写入变量或触发命令
-> 离开页面时执行【停止监听广播】推送目标绑定：
用户登录或设备绑定成功
-> 执行【读取极光推送RegId】
-> 将 RegId、用户、设备唯一标识和更新时间提交到服务端
-> 用户退出登录或设备解绑时清理服务端关系关键能力说明
打开 APP 内置页面
【打开APP的内置页面】用于从活字格页面打开 HAC 的原生页面。目标页面包括“配置”和“快速设置”两类：配置页面适合逐项修改，快速设置页面适合通过扫码一次完成设备配置。
返回活字格页面后，应重新读取或校验服务器地址、扫描头、UHF、推送等关键配置，避免继续使用旧状态。
读取 APP 和设备信息
【读取APP信息】返回当前 HAC 的版本号和包名；如果页面不在 HAC 中运行，版本号和包名均为 N/A。可用它判断运行环境、记录问题环境或提示升级。
【读取APP信息到单元格】应使用独立单元格保存版本号、包名和读取状态，避免与业务输入混在一起。
【读取设备唯一标识】通常返回设备的 SSAID / Android ID，可用于设备绑定、操作审计和问题排查，但不能单独作为高安全认证凭据。涉及放行、审核等关键操作时，仍需结合账号、角色和业务规则。
强制关闭 APP
【强制关闭APP】会立即关闭当前 APP，可能中断未提交的数据和正在执行的操作。仅适合运维、异常恢复或明确结束 APP 的场景，不要放在普通业务完成动作或容易误触的位置。执行前应保存状态并提示用户。
预览 PDF 文件
【预览PDF文件】接收 PDF 文件 URL、保存到“下载”文件夹的文件名和 PDF 密码。文件名建议带 .pdf 后缀；去掉后缀后的文件名可作为预览标题。
需要确认 URL 在 HAC 中可访问，登录态或下载令牌没有过期。文件会保存到设备下载目录，项目还应明确文件清理和敏感 PDF 的访问范围。该命令不能保证无预览直接打印，打印机选择、纸型等能力取决于设备系统和现有配置。
拨打电话
【拨打电话】调用后会自动弹出拨号画面并拨出电话。调用前应展示被呼叫对象和号码，号码应来自可信业务数据或经过格式校验；对外呼叫建议记录操作人、时间、业务对象和号码来源。若项目只需要打开拨号界面而不立即拨出，应先确认插件在目标设备上的实际行为。
读取极光推送 RegId
【读取极光推送RegId】返回极光推送注册 ID，用于绑定推送目标。重新安装 APP、包名变化或推送配置变化后，RegId 可能变化，不同包名的 RegId 不能混用。服务端建议同时记录用户、设备唯一标识、APP 版本和更新时间，退出登录或设备解绑时清理对应关系。
震动和提示音
【震动提醒】可设置持续时间，成功反馈适合短震动，失败、重复或不匹配可使用更明显的震动。不要在高频回调中无限触发。
【播放提示音】支持通知提示音、闹钟和铃声类型。现场页面不能只依赖声音反馈，关键结果还应通过页面状态、文字、颜色或震动表达。
发送广播
【发送广播】是异步单向动作，插件参数与 Android Intent 的对应关系如下：
| 插件参数 | Android Intent |
|---|---|
| Action | Intent 的 Action |
| Type | Intent 的 MIME Type |
| Uri | Intent 的 Data |
| IntentExtras | Intent 的 Extra |
Extra 的名称、类型和值应来自厂商或目标 APP 文档。类型以插件实际支持范围为准，常见类型包括 bool、int、float 和 string。广播已发送不代表目标 APP 已处理，页面不能把发送成功当作业务完成。
接收和停止广播
【开始接收广播】监听指定 Action，并在回调中返回监听器注册 ID 和 Extra JSON。Extra JSON 中每个 Extra 应按 name、type、value 等字段解析。页面应保存注册 ID，按业务规则处理空 Extra、格式不匹配和重复回调。
【停止监听广播】需要使用开始监听时返回的注册 ID。离开页面、任务完成、切换模式、打开会打断流程的弹窗或收到预期结果后，应停止不再需要的监听，避免旧页面继续写入数据。
设计要点
- 原生能力入口要放在明确按钮后，不要由页面加载或扫码成功自动触发危险动作；
- PDF、电话、强制关闭、广播发送前要说明即将发生什么；
- 震动和提示音要搭配页面状态，嘈杂或静音环境下仍能理解结果；
- 广播、扫码、BLE 订阅、物理按键这类监听能力都要绑定页面生命周期；
- 读取 APP、设备、RegId 等信息时，建议写入隐藏字段或日志，不和业务输入混在一起；
- 电话、设备标识、RegId 和 PDF 等信息应按项目的权限和留存规则保护。
异常处理
| 异常 | 常见原因 | 推荐处理 |
|---|---|---|
APP 信息返回 N/A | 不在 HAC 中运行 | 提示设备能力不可用或切换兼容流程 |
| 设备标识为空 | 容器不支持、系统限制或命令失败 | 提示重试并记录 APP 版本、设备型号和错误信息 |
| 内置页面返回后状态未更新 | 原生页面修改了配置，Web 页面仍使用旧状态 | 返回后重新读取关键配置 |
| PDF 无法预览 | URL 不可访问、文件名异常、密码错误或登录态过期 | 提示检查地址、文件名和密码，保留重新预览入口 |
| PDF 文件泄露或占用空间 | 文件长期保存在下载目录 | 按项目规则限制访问并提供清理策略 |
| 电话未拨出 | 号码为空、格式错误、系统限制或命令行为与预期不符 | 提示检查号码，允许复制或手动拨号 |
| RegId 为空或已失效 | 推送未初始化、重新安装或包名配置变化 | 重新读取并更新服务端绑定关系 |
| 震动 / 提示音无效 | 设备不支持、系统静音、音量低或系统设置限制 | 同时提供视觉反馈 |
| 广播无响应 | Action / Extra 不匹配、目标 APP 未安装 | 显示已发送但无法确认结果，并提示检查配置 |
| 接收不到广播 | 未开始监听、Action 不匹配、监听已停止 | 允许重新监听并记录监听器 ID |
| 广播重复回调 | 外部程序重复发送、页面重复注册 | 按业务键去重，离开页面时停止旧监听 |
兼容性与安全边界
- 在项目测试记录中保存 HAC 版本、Android 版本、设备型号、厂商程序版本和插件版本；
- 对电话、通知、文件和设备标识等能力，按目标 Android 版本确认权限和系统设置；
- 普通浏览器只能走兼容流程，不能假定能够调用 HAC 的原生能力；
- 设备唯一标识和 RegId 用于识别或推送绑定，不替代账号认证；
- 需要高安全等级的业务，应结合账号、角色、时间、位置和服务端校验；
- 广播参数和接收数据来自外部程序时，应校验来源、格式和业务范围。
验收标准
- 页面能通过【读取APP信息】区分
HAC环境和普通浏览器环境。 - 每个命令都有明确的输入参数、输出位置或回调处理方式。
- PDF 预览能正确使用文件名、密码和下载地址，并能在失败时提示原因。
- 拨打电话、强制关闭 APP、发送广播等动作有明确入口和必要确认，不会被误触发。
- 广播监听页面能保存监听器注册 ID，并在离开页面或任务结束时停止监听。
- 震动和提示音有视觉反馈兜底，不会在高频流程中连续无限触发。
- 设备绑定和推送绑定能记录必要的 APP、设备、用户和更新时间信息，并能在解绑时清理关系。