简介

面向开发者的 OneKey 硬件钱包集成文档，适用于 Web 和原生应用。

本页是入门层 —— 帮你选对 SDK 包并装上。端到端流程（搜设备 → 事件 → PIN/passphrase → 首次签名）和参数、事件、错误处理的完整说明，请看 Core API Guide。

选择传输协议

USB 场景一律推荐 @onekeyfe/hd-common-connect-sdk。@onekeyfe/hd-web-sdk 仅用于插件端（iframe 嵌入形式）。

连接方式

平台指南

低层协议与自定义通道参考：底层传输插件与协议

安装 SDK

按运行时选择一个入口安装：

# Web / 桌面 WebUSB（推荐）
npm i @onekeyfe/hd-common-connect-sdk
 
# React Native BLE
npm i @onekeyfe/hd-ble-sdk
 
# 原生宿主 + 底层插件（Android/iOS/Flutter 桥接）
npm i @onekeyfe/hd-common-connect-sdk
 
# 插件端 iframe（仅插件端）
npm i @onekeyfe/hd-web-sdk

传输细节：

• WebUSB：WebUSB 指南
• React Native BLE：BLE 指南
• 原生 Android / iOS / Flutter：通过底层传输插件桥接 JS，见各平台页面。
• 自定义通道与协议：底层传输插件与协议

初始化 SDK

按照运行时选择对应的初始化方式，避免混用。

Web / 桌面 WebUSB

使用 @onekeyfe/hd-common-connect-sdk：

import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
 
await HardwareSDK.init({
  env: 'webusb',
  debug: process.env.NODE_ENV !== 'production',
  fetchConfig: true,
});

React Native BLE

使用 @onekeyfe/hd-ble-sdk：

import HardwareSDK from '@onekeyfe/hd-ble-sdk';
 
await HardwareSDK.init({
  debug: __DEV__,
});

原生桥接 / 低层协议

使用 @onekeyfe/hd-common-connect-sdk：

import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
 
await HardwareSDK.init({
  env: 'lowlevel',
  debug: process.env.NODE_ENV !== 'production',
  fetchConfig: true,
});

插件端 Iframe

使用 @onekeyfe/hd-web-sdk（仅插件端）：

import { HardwareSDK } from '@onekeyfe/hd-web-sdk';
 
await HardwareSDK.init({
  debug: process.env.NODE_ENV !== 'production',
  connectSrc: 'https://jssdk.onekey.so/1.1.19/', // iframe host
});

下一步

HardwareSDK.init(...) 完成之后，剩下的流程 —— 设备发现、事件绑定、PIN/passphrase 处理、签名 —— 都在 Core API Guide 里端到端讲清楚了：

• 标准生命周期（init → search → getFeatures → subscribe → call + uiResponse → cleanup）：Core API Guide → 标准生命周期
• 所有方法都接受的调用参数：通用参数
• 标识符参考（connectId / deviceId / passphraseState / …）：Identifiers
• PIN 输入流程：PIN 码
• Passphrase / 隐藏钱包流程：Passphrase

设备与传输兼容性

蓝牙、USB 和 Air-Gap 连接的支持状态

设备	蓝牙	USB	Air-Gap
OneKey Classic 1s 经典款 Classic 1s	Supported	Supported	N/A
OneKey Classic 1s Pure Classic 1s Pure 无电池版本	Supported	Supported	N/A
OneKey Mini 紧凑型 USB 钱包	N/A	Supported	N/A
OneKey Touch 全触屏体验	Supported	Supported	N/A
OneKey Pro 旗舰版，支持指纹识别	Supported	Supported	Supported

Air-Gap 模式： OneKey Pro 支持通过二维码进行离线签名（Air-Gap）— 无需 USB 或蓝牙连接，提供最高级别的安全性。详见 Air-Gap 集成。

核心包

包名	用途	NPM	版本
@onekeyfe/hd-common-connect-sdk	统一的 Web/原生 SDK 接口；推荐作为传输层入口	npm
@onekeyfe/hd-ble-sdk	纯 React Native 蓝牙协议栈（推荐用于 RN 项目）	npm
@onekeyfe/hd-transport-react-native	React Native 传输层副作用/桥接	npm
@onekeyfe/hd-transport-web-device	Web 环境设备访问传输层	npm
@onekeyfe/hd-transport-emulator	模拟器传输层（无需物理设备即可开发和测试）	npm
@onekeyfe/hd-transport-http	HTTP 桥接传输层	npm
@onekeyfe/hd-transport-lowlevel	底层主机适配器协议（用于原生集成）	npm
@onekeyfe/hd-core	核心事件、常量、消息处理	npm
@onekeyfe/hd-shared	共享工具和类型	npm
@onekeyfe/hd-web-sdk	Web SDK 封装（不推荐；建议使用 hd-common-connect-sdk）	npm

• 更新日志：releases 

延伸阅读

• 底层传输与消息协议（调试 / 自定义适配器场景）：底层传输插件
• 从老的 hd-web-sdk 方案迁移：迁移指引

支持

致用户：本文档主要面向开发者。如果您在使用我们的产品时遇到问题，请查阅帮助中心或提交工单。

• 帮助中心 
• 讨论区 
• 问题反馈 

相关仓库

• OneKey App (app-monorepo) 
• OneKey 固件 
• OneKey 硬件 JS SDK 

立即体验