本页目录

迁移到 common-connect-sdk

从 Bridge 迁移到 WebUSB，并切换到 @onekeyfe/hd-common-connect-sdk。

环境要求

Chromium 内核浏览器（Chrome/Edge 桌面版）
Node.js 18+（推荐 LTS 版本）

变更概览

SDK 入口：@onekeyfe/hd-web-sdk → @onekeyfe/hd-common-connect-sdk
初始化选项：使用 env: 'webusb'；不再需要 connectSrc（无 iframe）
权限流程：调用 navigator.usb.requestDevice()（必须由用户手势触发）并使用官方过滤器 ONEKEY_WEBUSB_FILTER
事件系统：使用 @onekeyfe/hd-core 的 UI_EVENT / DEVICE 事件处理用户交互（PIN/Passphrase 等）
移除 Bridge 相关逻辑：删除 checkBridgeStatus() 和所有 Bridge 检查/提示
业务 API 基本不变：如 searchDevices / getDeviceState / btcGetAddress

安装


npm i @onekeyfe/hd-common-connect-sdk @onekeyfe/hd-core @onekeyfe/hd-shared

初始化（hd-common-connect-sdk + WebUSB）


import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
 
const initialized = await HardwareSDK.init({
  env: 'webusb',
  debug: false,
  fetchConfig: true,
});
if (!initialized) throw new Error('SDK initialization failed');

与 hd-web-sdk 不同，这里不需要 connectSrc（无 iframe 依赖）。
建议启用 fetchConfig: true 以获取设备能力和提示配置。

绑定 UI 和设备事件（PIN / Passphrase / 插拔）

受保护调用前，注册 Core API UI 处理器。保留请求关联字段，只回复输入请求；用户取消时取消所选连接上的操作。设备端 PIN 和按键提示不需要 uiResponse。

订阅 DEVICE.CONNECT 和 DEVICE.DISCONNECT 来刷新连接状态，不要记录完整设备对象或 UI 事件 payload。

授权（WebUSB 选择器 + 官方过滤器）


import { ONEKEY_WEBUSB_FILTER } from '@onekeyfe/hd-shared';
 
// 重要：必须由用户手势触发（如按钮点击），否则浏览器会阻止
await navigator.usb.requestDevice({ filters: ONEKEY_WEBUSB_FILTER });

枚举设备并进行首次调用


// 1) Enumerate
const list = await HardwareSDK.searchDevices();
if (!list.success) throw new Error(list.payload.error);
// Select explicitly in the application when more than one device is available.
if (list.payload.length !== 1) throw new Error('Select exactly one device before continuing');
const { connectId } = list.payload[0] ?? {};
if (!connectId) throw new Error("No device connection");
 
// 2) Confirm deviceId
const state = await HardwareSDK.getDeviceState(connectId);
if (!state.success) throw new Error(state.payload.error);
const resolvedDeviceId = state.payload.identity.deviceId;
if (!resolvedDeviceId) throw new Error("Device has no wallet identity");
 
// 3) Example: get a BTC address
const r = await HardwareSDK.btcGetAddress(connectId, resolvedDeviceId, {
  path: "m/44'/0'/0'/0/0",
  coin: 'btc',
  showOnOneKey: true,
  useEmptyPassphrase: true,
});
 
if (r.success) {
  console.log('BTC address:', r.payload.address);
} else {
  console.error('Error:', r.payload.error, r.payload.code);
}

清理和检查清单

依赖替换：移除 @onekeyfe/hd-web-sdk，使用 @onekeyfe/hd-common-connect-sdk
初始化变更：
- 旧：env: 'web' + connectSrc: 'https://jssdk.onekey.so/.../'
- 新：env: 'webusb'（无 connectSrc）
移除 Bridge 相关逻辑：如 checkBridgeStatus()、Bridge 安装/重启提示
绑定 UI_EVENT / DEVICE：确保处理 PIN/Passphrase 和设备插拔事件
未授权的设备需要用户授权：requestDevice() 必须由用户手势触发；已授权设备可直接枚举
兼容性提示：如果 navigator.usb 不存在，提示用户切换到支持 WebUSB 的浏览器

常见问题

HTTP 下没有权限提示？→ 使用 HTTPS
UI 请求似乎卡住？→ 尽早订阅 UI_EVENT，仅对输入请求回复 uiResponse，设备通知显示提示即可
还在使用 connectSrc 或 HdWebSdk.HardwareWebSdk？→ 已迁移到 hd-common-connect-sdk；不再需要 iframe
在用户手势之外调用 requestDevice？→ Chrome 会阻止；必须由点击等手势触发