本页目录

迁移到 web-sdk + WebUSB

将 Bridge 替换为 WebUSB，保持使用 @onekeyfe/hd-web-sdk。

环境要求

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

变更概览

使用 env: 'webusb' 初始化 SDK
- （Bridge (env: web) → WebUSB (env: webusb)）
优先省略 connectSrc，让 @onekeyfe/hd-web-sdk 填 https://jssdk.onekey.so/<安装版本>/。只有自建 iframe 时才覆盖。
通过 navigator.usb.requestDevice() 配合官方 OneKey 过滤器请求用户授权 — 由于 Chrome 安全限制，必须由用户手势触发（如按钮点击）；未授权设备需要先授权，已授权设备可直接枚举
Bridge 相关检查已弃用（如 checkBridgeStatus()）
其他 SDK 用法保持不变

初始化（hd-web-sdk + WebUSB）


import HdWebSdk from '@onekeyfe/hd-web-sdk';
 
// Same pattern as expo-example: default export → .HardwareWebSdk
const HardwareSDK = HdWebSdk.HardwareWebSdk;
 
const initialized = await HardwareSDK.init({
  env: 'webusb',
  // omit connectSrc — SDK fills https://jssdk.onekey.so/<installed-hd-web-sdk-version>/
  debug: false,
  fetchConfig: true,
});
if (!initialized) throw new Error('SDK initialization failed');

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


import { ONEKEY_WEBUSB_FILTER } from '@onekeyfe/hd-shared';
 
// 重要：必须由用户手势触发（如按钮点击）
// Request permission for an unauthorized device from a user gesture.
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: 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);
}

清理和检查清单

移除 Bridge 相关检查/CTA（如 checkBridgeStatus()）
除非自建 iframe，否则省略 connectSrc；覆盖时必须与安装的 @onekeyfe/hd-web-sdk 版本一致
检测 navigator.usb 特性，如不支持则显示友好提示
其他 SDK 方法和 UI 流程保持不变