Introducción

Documentación para desarrolladores que integran hardware OneKey en aplicaciones web y nativas.

Hardware SDK 1.2.x admite Protocol V1 y Protocol V2 mediante la misma API de JavaScript. ¿Acabas de empezar? Comienza con Primeros pasos.

Esta página presenta la guía de orientación: elige el paquete SDK adecuado para tu plataforma e instálalo. Para el recorrido completo (búsqueda → eventos → PIN/passphrase → primera llamada de firma), así como parámetros, eventos y gestión de errores, consulta la Guía de la API Core.

Elige tu transporte

Las integraciones USB deben usar @onekeyfe/hd-common-connect-sdk; usa @onekeyfe/hd-web-sdk solo cuando el host requiera una configuración de iframe/plugin.

Métodos de conexión

Guía por plataforma

Protocolo de bajo nivel y canales personalizados: Plugin y protocolo de transporte de bajo nivel

Instalar el SDK

Elige un punto de entrada según el entorno de ejecución:

# Web / desktop WebUSB (recommended)
npm i @onekeyfe/hd-common-connect-sdk
 
# React Native BLE
npm i @onekeyfe/hd-ble-sdk
 
# Native host with low-level plugin (Android/iOS/Flutter bridge)
npm i @onekeyfe/hd-common-connect-sdk
 
# Plugin iframe host only (plugin-only)
npm i @onekeyfe/hd-web-sdk

Detalles de los transportes:

• WebUSB: Guía de WebUSB
• BLE en React Native: Guía de BLE
• Android / iOS / Flutter nativos: conecta las llamadas JS mediante plugins de transporte de bajo nivel (consulta los ejemplos en sus páginas).
• Canal y protocolo personalizados: Plugin y protocolo de transporte de bajo nivel

Inicializar el SDK

Usa el método de inicialización correspondiente a tu entorno de ejecución; evita mezclar puntos de entrada del SDK.

WebUSB en web / escritorio

Usa @onekeyfe/hd-common-connect-sdk:

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

React Native BLE

Usa @onekeyfe/hd-ble-sdk:

import HardwareSDK from '@onekeyfe/hd-ble-sdk';
 
const initialized = await HardwareSDK.init({
  debug: false,
});
if (!initialized) throw new Error('SDK initialization failed');

Puente nativo / bajo nivel

Usa @onekeyfe/hd-common-connect-sdk:

import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
import type { LowlevelTransportSharedPlugin } from '@onekeyfe/hd-transport';
 
// Provide an implemented native BLE bridge; this is a preparation fragment.
declare const plugin: LowlevelTransportSharedPlugin;
const initialized = await HardwareSDK.init({
  env: 'lowlevel',
  debug: false,
  fetchConfig: true,
}, undefined, plugin);
if (!initialized) throw new Error('SDK initialization failed');

Host iframe de plugin

Usa @onekeyfe/hd-web-sdk (solo plugin). El host iframe predeterminado del SDK es https://jssdk.onekey.so/<installed-package-version>/ de getSDKVersion(). Omite connectSrc salvo que alojes el iframe por tu cuenta.

Esta compilación de la documentación corresponde a Hardware SDK 1.2.8-alpha.12. El host iframe predeterminado es https://jssdk.onekey.so/1.2.8-alpha.12/. Omite connectSrc para que el SDK use la versión del paquete instalado. Sobrescríbelo solo si alojas el iframe por tu cuenta y haz que coincida con la versión instalada de @onekeyfe/hd-web-sdk.

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

Próximos pasos

Después de que HardwareSDK.init(...) devuelva un resultado, sigue Primeros pasos para obtener la primera dirección y después la Guía de la API Core para el resto del flujo:

• Matriz de dispositivos de 1.2.0: Dispositivos

• Qué cadenas admite Pro 2 / Neo: Compatibilidad de cadenas

• Protocol V1 frente a V2 (detección automática): Protocolo

• Abrir / reanudar una cartera: Sesiones de cartera

• Selección de transporte y reconexión: Transporte · Reconexión

• Firmware V2 / V3 / V4: Actualización del firmware

• Ciclo de vida estándar (init → search → getDeviceState → subscribe → call + uiResponse → cleanup): Guía de la API Core → ciclo de vida estándar

• Parámetros compartidos para los métodos de dirección, firma y dispositivo: Parámetros comunes

• Referencia de identificadores (connectId / deviceId / passphraseState / …): Identificadores

• Flujo de introducción del PIN: Código PIN

• Flujo de passphrase / cartera oculta: Frase de contraseña

Compatibilidad de dispositivos y transportes

Compatibilidad con Bluetooth, USB, Air-Gap y familia de protocolo

Dispositivo	Protocolo	Bluetooth	USB	Air-Gap
OneKey Classic 1s OneKey Classic 1s	V1	Compatible	Compatible	No compatible
OneKey Classic 1s Pure Edición sin batería	V1	Compatible	Compatible	No compatible
OneKey Mini Cartera compacta solo USB	V1	No compatible	Compatible	No compatible
OneKey Touch Experiencia totalmente táctil	V1	Compatible	Compatible	No compatible
OneKey Pro Gama premium con seguridad por huella	V1	Compatible	Compatible	Compatible
OneKey Pro 2 Edición profesional Protocol V2	V2	Compatible	Compatible	Compatible
OneKey Neo Edición compacta Protocol V2, sin cámara	V2	Compatible	Compatible	No compatible

Modo Air-Gap: OneKey Pro y Pro 2 permiten firmar de forma aislada mediante códigos QR, sin conexión USB ni Bluetooth, y revisar los detalles en el dispositivo antes de firmar. Consulta Integración Air-Gap para más detalles.

Paquetes principales

Paquete	Finalidad	NPM	Versión
@onekeyfe/hd-common-connect-sdk	API unificada del SDK para web y nativo; punto de entrada recomendado para transportes	npm
@onekeyfe/hd-ble-sdk	Implementación BLE puramente React Native (recomendada para proyectos RN)	npm
@onekeyfe/hd-transport-react-native	Efectos secundarios de registro del transporte / puente de React Native	npm
@onekeyfe/hd-transport-web-device	Transporte web para acceder al dispositivo en entornos web	npm
@onekeyfe/hd-transport-emulator	Transporte de emulador (desarrolla y prueba sin un dispositivo físico)	npm
@onekeyfe/hd-transport-http	Transporte mediante puente HTTP	npm
@onekeyfe/hd-transport-lowlevel	Contrato del adaptador de host de bajo nivel (para integraciones nativas)	npm
@onekeyfe/hd-core	Eventos, constantes y conexión de mensajes de Core	npm
@onekeyfe/hd-shared	Utilidades y tipos compartidos	npm
@onekeyfe/hd-web-sdk	Wrapper del SDK web (no recomendado; prefiere hd-common-connect-sdk)	npm

• Registro de cambios: versiones 

Más información

• Transporte de bajo nivel y protocolo de mensajes (para depuración o adaptadores personalizados): Plugin de transporte de bajo nivel
• Migración desde el flujo antiguo hd-web-sdk: Guía de migración

Soporte

Para usuarios: esta documentación está dirigida principalmente a desarrolladores. Si tienes problemas al usar nuestros productos, consulta el Centro de ayuda o envía una solicitud de soporte.

• Centro de ayuda 
• Incidencias 

Repositorios relacionados

• OneKey App (app-monorepo) 
• Firmware de OneKey 
• OneKey Hardware JS SDK 

Pruébalo