Conecta tu primer dispositivo

Instala Hardware SDK 1.2.x, conecta un dispositivo y confirma tu primera dirección.

Esta página explica los primeros pasos. Una vez que funcione, elige una guía de transporte y lee la Guía de la API Core para conocer el PIN, la passphrase, los eventos y la firma.

Hardware SDK 1.2.0 se comunica con Protocol V1 (Classic / Mini / Touch / Pro) y Protocol V2 (Pro 2 / Neo) mediante la misma API de JavaScript. No eliges el protocolo en init().

1. Elige un paquete

npm i --save-exact @onekeyfe/[email protected] @onekeyfe/[email protected] @onekeyfe/[email protected]

pnpm add --save-exact @onekeyfe/[email protected] @onekeyfe/[email protected] @onekeyfe/[email protected]

yarn add --exact @onekeyfe/[email protected] @onekeyfe/[email protected] @onekeyfe/[email protected]

El comando selecciona paquetes publicados 1.2.x y guarda versiones exactas. Mantén los paquetes SDK, core y shared en la misma versión e incluye el lockfile en el commit. Si integras @onekeyfe/hd-web-sdk, omite connectSrc para que coincida con el paquete instalado.

2. Inicializa una sola vez

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

Llama a init() una sola vez al iniciar la aplicación. No mezcles @onekeyfe/hd-web-sdk y @onekeyfe/hd-common-connect-sdk en el mismo entorno de ejecución.

3. Busca, identifica y lee una dirección

Registra el controlador de eventos de interfaz antes de las llamadas protegidas para que los dispositivos bloqueados puedan completar la introducción del PIN. Para WebUSB, autoriza el dispositivo desde el botón Conectar del usuario antes de buscarlo:

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

A continuación, busca dispositivos. Este ejemplo requiere exactamente un candidato; si hay varios dispositivos disponibles, permite que el usuario seleccione uno antes de continuar.

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

Comprueba siempre success antes de leer payload. useEmptyPassphrase: true mantiene esta primera llamada en la cartera estándar para que una sesión residual de cartera oculta no cambie la dirección silenciosamente.

getDeviceState() es la consulta compatible con V1/V2. getFeatures() es exclusivo de Protocol V1; Pro 2 y Neo deben usar getDeviceState().

WebUSB requiere HTTPS y un gesto del usuario. BLE requiere permiso Bluetooth del sistema operativo.

Compatibilidad de dispositivos y carteras

• El SDK detecta Protocol V1 o V2 a partir del dispositivo conectado. No diferencies los casos según el PID de USB, el nombre BLE ni la cadena de producto. Consulta Protocol V1 y V2.
• Pro 2 y Neo usan los mismos métodos que Classic / Pro. Las diferencias entre dispositivos se detallan en Dispositivos.
• Abre o cambia de cartera con openWalletSession. getPassphraseState está obsoleto. Consulta Sesiones de cartera.

Siguiente

1. Si ya usas 1.1.x: Actualizar a Hardware SDK 1.2
2. Conecta los eventos de interfaz de PIN / passphrase: Guía de la API Core
3. Establece una conexión real en tu plataforma: Transporte
4. Gestiona las desconexiones: Desconexiones y reconexión
5. Qué cadenas admite cada dispositivo: Compatibilidad de cadenas
6. Firma una transacción: Guías de firma
7. Firmware: Actualización del firmware
8. Prueba sin hardware: Playground