跳到主要内容

迁到 WebUSB

如果暂时不能替换 @ukeyfe/hardware-web-sdk 包名，但想先把底层连接从 Bridge 改成 WebUSB，可以采用这条过渡路线：保留 SDK 入口，只调整初始化环境和授权方式。

前提​

  • 请使用基于 Chromium 的桌面浏览器，例如 Chrome 或 Edge。
  • Node.js 建议 18 及以上，最好直接使用 LTS 版本。

改动点​

  • 初始化环境从 Bridge 的 env: 'web' 改为 WebUSB 的 env: 'webusb'。
  • hardware-web-sdk 仍需要 connectSrc，请保持为当前可用的 iframe 主机版本，例如 https://jssdk.demo.example/1.1.16/。
  • USB 设备授权改为 navigator.usb.requestDevice()，并使用官方 UKey Wallet 过滤器。
  • 设备选择器必须由用户手势触发；在授权前不要自动发现设备。
  • Bridge 检查逻辑（如 checkBridgeStatus()）不再适用于 WebUSB。
  • 链 API 的调用方式通常不需要改动。

初始化接入（hardware-web-sdk + WebUSB）​

import HardwareWebSdk from "@ukeyfe/hardware-web-sdk";

// 继续沿用 hardware-web-sdk 的默认导出方式。
const ukeySdk = HardwareWebSdk.HardwareWebSdk;

await ukeySdk.init({
  env: "webusb",
  // hardware-web-sdk 依旧需要配置 iframe 宿主。
  connectSrc: "https://jssdk.demo.example/1.1.16/",
  debug: true,
  fetchConfig: true,
});

申请USB权限​

import { UKEY_WEBUSB_FILTER } from "@ukeyfe/hardware-shared";

// 从用户可见的操作触发；拿到权限后再继续扫描设备。
// 授权之前，浏览器不会把 USB 设备暴露给页面。
await navigator.usb.requestDevice({ filters: UKEY_WEBUSB_FILTER });

扫描并调用​

// 1) 扫描设备
const deviceList = await ukeySdk.searchDevices();
if (!deviceList.success) throw new Error(deviceList.payload.error);
const { connectId, deviceId } = deviceList.payload[0] ?? {};

// 2) （按需执行）再拉取设备特征信息，用返回的钱包标识兜底
const featureInfo = await ukeySdk.getFeatures(connectId);
if (!featureInfo.success) throw new Error(featureInfo.payload.error);
const resolvedDeviceId = featureInfo.payload.device_id ?? deviceId;

// 3) 参考写法：读取 BTC 地址
const addressResult = await ukeySdk.btcGetAddress(connectId, resolvedDeviceId, {
  path: "m/84'/0'/2'/0/0",
  coin: "btc",
  showOnUKey: false,
});

if (addressResult.success) {
  console.log("解析出的 BTC 地址:", addressResult.payload.address);
} else {
  console.error("调用失败:", addressResult.payload.error, addressResult.payload.code);
}

收尾清单​

  • 移除 Bridge 专属检查和提示，例如 checkBridgeStatus()。
  • connectSrc 仍然需要保留，并指向最新 iframe 主机。
  • 在页面中检测 navigator.usb，不支持时给出浏览器兼容提示。
  • 链 API、PIN、Passphrase 等上层流程保持原有处理方式。