Conexión WebUSB

Conecta una aplicación de navegador directamente a OneKey con @onekeyfe/hd-common-connect-sdk. Este flujo no requiere un iframe ni OneKey Bridge.

Requisitos

• Un navegador compatible con WebUSB y un contexto seguro. Comprueba la disponibilidad de navigator.usb; muestra un mensaje sobre navegadores compatibles si no está disponible.
• Una acción del usuario para abrir el selector USB.
• Un dispositivo OneKey inicializado y un cable USB que transmita datos.
• gestión de eventos de interfaz para PIN, frase de contraseña y confirmación en el dispositivo.

1. Instalar e inicializar

npm i @onekeyfe/hd-common-connect-sdk @onekeyfe/hd-core @onekeyfe/hd-shared

Mantén los paquetes SDK en la misma versión. Inicializa una vez al arrancar la aplicación:

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

2. Registrar eventos de interfaz

Usa el controlador de interfaz de la API Core completo antes de leer una dirección o firmar. Distingue solicitudes de entrada de notificaciones del dispositivo y conserva la correlación de respuesta.

Tu aplicación aporta los diálogos. La entrada de PIN en el host necesita un teclado ciego; los avisos exclusivos del dispositivo de PIN y botones necesitan una pantalla de instrucciones, no un botón de aprobación del host. Cancela la operación SDK seleccionada si el usuario cancela y elimina los listeners al cerrar la integración.

3. Autorizar desde una acción del usuario

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

Gestiona la cancelación del selector en el controlador del botón. Abrir el selector no demuestra que el dispositivo esté inicializado. Los dispositivos autorizados previamente pueden enumerarse sin volver a abrirlo.

4. Seleccionar la conexión y leer la identidad

const result = await HardwareSDK.searchDevices();
if (!result.success) throw new Error(result.payload.error);
if (!result.payload.length) throw new Error('No OneKey device found');
 
// This example requires one device. Use a device selector for multiple candidates.
if (result.payload.length !== 1) throw new Error('Select a device before continuing');
const { connectId } = result.payload[0];
if (!connectId) throw new Error('Device connection is unavailable');
 
const state = await HardwareSDK.getDeviceState(connectId);
if (!state.success) throw new Error(state.payload.error);
const deviceId = state.payload.identity.deviceId;
if (!deviceId) throw new Error('Device has no wallet identity');

No supongas que el descubrimiento incluye deviceId ni deduzcas el protocolo a partir de descriptores USB. Consulta Buscar dispositivos.

5. Confirmar una dirección de recepción

const address = await HardwareSDK.btcGetAddress(connectId, deviceId, {
  path: "m/84'/0'/0'/0/0",
  coin: 'btc',
  showOnOneKey: true,
  useEmptyPassphrase: true,
});
if (!address.success) throw new Error(address.payload.error);
 
// Display address.payload.address in your application after device confirmation.

Este ejemplo selecciona explícitamente la cartera estándar. Para una cartera oculta, ábrela con openWalletSession y envía su passphraseState en llamadas de dirección y firma. Mantén coherentes el contexto de cartera y la ruta de derivación.

Desconexión y limpieza

• Suscríbete a DEVICE.DISCONNECT e invalida la conexión actual en la interfaz.
• Vuelve a enumerar y leer el estado tras reconectar.
• Ejecuta llamadas en serie por dispositivo. No repitas automáticamente una solicitud de firma o actualización de firmware tras un tiempo agotado.
• Llama a dispose() al cerrar el SDK o cambiar transportes, e inicializa antes de volver a usarlo.

Consulta Desconexiones y reconexión.

Resolución de problemas

Continúa con Guías de firma o Códigos de error.