Skip to Content
硬件接入快速开始
HARDWARE SDK · WEBUSB

连接你的第一台设备

安装 Hardware SDK 1.2.x,通过 USB 连接 OneKey,并在设备上确认第一个以太坊地址。

本页只覆盖第一次跑通。跑通之后再选 传输指南,并阅读 Core API Guide 了解 PIN、passphrase、事件和签名。

Hardware SDK 1.2.0 用同一套 JavaScript API 同时支持 Protocol V1(Classic / Mini / Touch / Pro)和 Protocol V2(Pro 2 / Neo)。init() 里不需要选择协议。

开始前准备
  • 已完成初始化的 OneKey 设备,以及可传输数据的 USB 线
  • 支持 WebUSB 的浏览器,例如桌面版 Chrome 或 Edge
  • HTTPS 站点,或用于本地开发的 localhost

1. 选择 SDK 包

运行时包下一步
浏览器 / 桌面 WebUSB@onekeyfe/hd-common-connect-sdkWebUSB
React Native BLE@onekeyfe/hd-ble-sdkReact Native BLE
Android / iOS / Flutter 原生桥@onekeyfe/hd-common-connect-sdk(env: 'lowlevel')原生 BLE
仅 iframe 插件宿主@onekeyfe/hd-web-sdk插件 iframe 宿主
Terminal
npm i --save-exact @onekeyfe/[email protected] @onekeyfe/[email protected] @onekeyfe/[email protected]

这些命令选择已发布的 1.2.x,并保存精确版本。SDK、core 和 shared 应使用同一版本,并提交 lockfile。如果嵌入 @onekeyfe/hd-web-sdk,省略 connectSrc,让它跟安装包版本一致。

2. 只初始化一次

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

在应用入口调用一次 init()。不要在同一运行时混用 @onekeyfe/hd-web-sdk 和 @onekeyfe/hd-common-connect-sdk。

3. 搜设备、取身份、读地址

受保护调用前先注册 UI 事件处理器,以便锁定设备完成 PIN 输入。

直接在“连接设备”按钮的点击处理器中请求 USB 授权。浏览器需要用户手势才能打开设备选择器:

authorize.ts
import { ONEKEY_WEBUSB_FILTER } from '@onekeyfe/hd-shared'; if (!navigator.usb) throw new Error('WebUSB is unavailable in this browser'); await navigator.usb.requestDevice({ filters: ONEKEY_WEBUSB_FILTER });

授权后发现设备并读取钱包身份。下例要求只有一个候选设备;如果发现多个设备,请先让用户选择一个再继续。

const devices = await HardwareSDK.searchDevices(); if (!devices.success || !devices.payload.length) { throw new Error('No OneKey device found'); } // Select explicitly in the application when more than one device is available. if (devices.payload.length !== 1) throw new Error('Select exactly one device before continuing'); const { connectId } = devices.payload[0]; if (!connectId) throw new Error("Missing connectId"); const state = await HardwareSDK.getDeviceState(connectId); if (state.success === false) throw new Error(state.payload.error); const deviceId = state.payload.identity.deviceId; if (!deviceId) throw new Error("Device has no wallet identity"); const address = await HardwareSDK.evmGetAddress(connectId, deviceId, { path: "m/44'/60'/0'/0/0", useEmptyPassphrase: true, showOnOneKey: true, }); if (address.success === false) throw new Error(address.payload.error); console.log(address.payload.address);

读取 payload 之前必须先看 success。useEmptyPassphrase: true 把第一次调用钉在标准钱包,避免残留的隐藏钱包会话悄悄改掉地址。

getDeviceState() 是 V1/V2 读取入口。getFeatures() 只支持 Protocol V1;Pro 2 / Neo 必须用 getDeviceState()。

WebUSB 需要 HTTPS 和用户手势。BLE 需要系统蓝牙权限。

设备与钱包支持

  • SDK 根据设备实时响应识别 Protocol V1 / V2。不要用 USB PID、蓝牙名或产品字符串来分支。见 Protocol V1 与 V2。
  • Pro 2 和 Neo 使用与 Classic / Pro 相同的方法。机型差异见 设备。
  • 打开或切换钱包用 openWalletSession。getPassphraseState 已废弃。见 钱包会话。

下一步

ETHEREUM & EVM签署第一笔交易参数、费率类型和签名结果。
  1. 已经在 1.1.x:升级到 Hardware SDK 1.2
  2. 接 PIN / passphrase UI 事件:Core API Guide
  3. 按平台真正连上设备:传输
  4. 处理掉线:断线与重连
  5. 哪条链在哪台设备:链支持
  6. 签一笔交易:交易签名指引
  7. 固件:固件升级
  8. 没有真机时:交互演示
最后更新于