PIN说明

PIN 是大多数受保护操作都会遇到的用户验证步骤。SDK 不会自行弹出固定 UI，而是通过事件告诉应用“现在需要 PIN”，再由应用决定展示设备端输入或软件端盲输。

核心提示

• 当设备处于锁定状态，且当前请求需要授权时，会触发 UI_REQUEST.REQUEST_PIN。
• UKey Core 26 必须在设备上填写 PIN，不能走软件端盲输。
• 支持软件端 PIN 的型号也建议优先使用设备端输入，让 PIN 不进入宿主应用。

支持表（软件 PIN）

下表用于判断是否可以展示“在此屏幕输入”的选项。即使型号支持软件端 PIN，也建议把“改在设备上输入”作为默认路径。

设备系列	软件侧 PIN 输入	仅设备端输入
UKey Lite 24 / Lite 25	支持	否
UKey Core 26	不支持	是

UI 建议

• 展示一个聚焦的 PIN 对话框，不要同时弹出多层提示。
• 默认动作使用“改在设备上输入”；只有支持软件端 PIN 的型号才展示“在此屏幕输入”。
• 软件端 PIN 使用固定 3x3 键盘，界面只显示掩码，不回显真实数字。
• 收到关闭事件或受保护流程结束后，及时关闭 PIN 对话框。

PIN 映射表（软件键盘）

软件端九宫格布局：

7 8 9
4 5 6
1 2 3

软件键盘展示的是位置，发送给 SDK 的是映射后的值。下面的数组把界面上的 1..9 转换为设备需要的顺序：

const PIN_KEYPAD_MAP = ["7", "8", "9", "4", "5", "6", "1", "2", "3"];
let mappedPin = "";

function appendMappedPinDigit(slot: number) {
  // slot 表示用户点到的九宫格位置编号
  mappedPin += PIN_KEYPAD_MAP[slot - 1];
}

例如用户点击软件键 1 和 9，映射后得到 7 和 3，最终发送 73。

处理 PIN 事件

import { UI_EVENT, UI_REQUEST, UI_RESPONSE } from "@ukeyfe/hardware-core";

ukeySdk.on(UI_EVENT, (uiEvent) => {
  if (uiEvent.type === UI_REQUEST.REQUEST_PIN) {
    // 更建议：把 PIN 放到设备上完成输入。
    ukeySdk.uiResponse({
      type: UI_RESPONSE.RECEIVE_PIN,
      payload: "@@UKEY_INPUT_PIN_IN_DEVICE",
    });

    // 备用方式：仅在支持软件端 PIN 的机型上使用。
    const mappedPin = "73"; // 根据键盘位置换算
    ukeySdk.uiResponse({ type: UI_RESPONSE.RECEIVE_PIN, payload: mappedPin });
  }
});