本页目录
连接你的第一台设备
安装 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-sdk | WebUSB |
| React Native BLE | @onekeyfe/hd-ble-sdk | React Native BLE |
| Android / iOS / Flutter 原生桥 | @onekeyfe/hd-common-connect-sdk(env: 'lowlevel') | 原生 BLE |
| 仅 iframe 插件宿主 | @onekeyfe/hd-web-sdk | 插件 iframe 宿主 |
npm
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 授权。浏览器需要用户手势才能打开设备选择器:
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.x:升级到 Hardware SDK 1.2
- 接 PIN / passphrase UI 事件:Core API Guide
- 按平台真正连上设备:传输
- 处理掉线:断线与重连
- 哪条链在哪台设备:链支持
- 签一笔交易:交易签名指引
- 固件:固件升级
- 没有真机时:交互演示