本页目录

WebUSB 连接指南

通过 @onekeyfe/hd-common-connect-sdk，让浏览器应用直接连接 OneKey。这条接入路径不需要 iframe 或 OneKey Bridge。

步骤 1. 要求

支持 WebUSB 的浏览器与安全上下文。检测 navigator.usb；不可用时提示用户使用受支持的浏览器。
用于打开 USB 选择器的用户手势。
已初始化的 OneKey 设备，以及可传输数据的 USB 线。
处理 PIN、密码短语和设备确认的 UI 事件处理器。

步骤 2. 安装


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

SDK 相关包应保持相同版本。

步骤 3. 初始化并绑定事件

在应用启动附近初始化一次：


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');

读地址或签名前，接入完整的 Core API UI 处理器。处理器需要区分输入请求和设备通知，并保留响应关联字段。

注意事项

应用负责提供弹窗。宿主端 PIN 输入需要盲键盘；设备端 PIN 和按键确认只显示操作提示，不能提供代替硬件确认的宿主按钮。用户取消时取消所选连接上的 SDK 操作，集成拆除时移除事件监听器。

步骤 4. 用户授权（带官方过滤器的选择器对话框）


import { ONEKEY_WEBUSB_FILTER } from '@onekeyfe/hd-shared';
 
// Call directly from the user's Connect button handler.
async function authorizeUsb() {
  if (!navigator.usb) throw new Error('WebUSB is unavailable in this browser');
  await navigator.usb.requestDevice({ filters: ONEKEY_WEBUSB_FILTER });
}

在按钮处理器中处理用户取消选择器的情况。打开选择器不代表设备已经初始化；之前已授权的设备可以直接枚举，无需每次重开选择器。

步骤 5. 枚举并选择设备


const result = await HardwareSDK.searchDevices();
if (!result.success) throw new Error(result.payload.error);
if (!result.payload.length) throw new Error('No OneKey device found');
 
// This example requires one device. Use a device selector for multiple candidates.
if (result.payload.length !== 1) throw new Error('Select a device before continuing');
const { connectId } = result.payload[0];
if (!connectId) throw new Error('Device connection is unavailable');
 
const state = await HardwareSDK.getDeviceState(connectId);
if (!state.success) throw new Error(state.payload.error);
const deviceId = state.payload.identity.deviceId;
if (!deviceId) throw new Error('Device has no wallet identity');

步骤 6. 读设备状态（需要时确认 deviceId）

上例在发现设备后调用 getDeviceState，并检查 identity.deviceId。不要假设发现结果已包含钱包身份，也不要从 USB 描述符推断协议。参见搜索设备。

步骤 7. 第一个调用示例（BTC 地址）


const address = await HardwareSDK.btcGetAddress(connectId, deviceId, {
  path: "m/84'/0'/0'/0/0",
  coin: 'btc',
  showOnOneKey: true,
  useEmptyPassphrase: true,
});
if (!address.success) throw new Error(address.payload.error);
 
// Display address.payload.address in your application after device confirmation.

此示例明确选择标准钱包，并要求在设备上确认收款地址。隐藏钱包应先通过 openWalletSession 打开，然后在地址和签名调用中使用同一个 passphraseState。钱包上下文和派生路径必须保持一致。

附录：最小 UI 辅助函数

请以 Core API UI 处理器为统一实现入口。不要直接复用缺少关联字段、取消路径或设备通知分支的弹窗代码。输入结束后清理秘密值，并使旧弹窗的提交回调失效。

断连与清理

订阅 DEVICE.DISCONNECT，在 UI 中使当前连接失效。
重连后重新枚举，并读取设备状态。
同一设备的调用串行执行，超时后不自动重复签名或固件升级请求。
拆除 SDK 或切换传输时调用 dispose()，再次使用前重新初始化。

参见断线与重连。

故障排查

现象	检查项
没有 `navigator.usb`	浏览器支持情况和安全上下文。
选择器未打开	是否直接从用户手势触发。
无法占用设备	其他标签页、应用或 Bridge 可能占用了设备；关闭该连接后再试。
调用一直等待输入	是否注册 UI 处理器、区分通知并转发响应关联字段。
账户与预期不同	核对 `deviceId`、路径以及明确的标准/隐藏钱包绑定。

继续

阅读交易签名指引或错误码。