On this page

Migrate to common-connect-sdk

Migrate from Bridge to WebUSB and switch SDK entry to @onekeyfe/hd-common-connect-sdk.

Requirements

Chromium browsers (Chrome/Edge desktop)
Node.js 18+ (LTS recommended)

What Changed (At a Glance)

SDK entry: @onekeyfe/hd-web-sdk → @onekeyfe/hd-common-connect-sdk
Init options: use env: 'webusb'; no more connectSrc (no iframe)
Permission flow: call navigator.usb.requestDevice() (must be triggered by a user gesture) with the official filter ONEKEY_WEBUSB_FILTER
Event system: use @onekeyfe/hd-core UI_EVENT / DEVICE events for user interaction (PIN/Passphrase, etc.)
Bridge-specific logic removed: drop checkBridgeStatus() and all Bridge checks/prompts
Business APIs mostly unchanged: e.g., searchDevices / getDeviceState / btcGetAddress

Install


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

Initialize (hd-common-connect-sdk + WebUSB)


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

Unlike hd-web-sdk, you do not need connectSrc here (no iframe dependency).
It is recommended to enable fetchConfig: true to fetch device capability and hint configurations.

Bind UI and Device Events (PIN / Passphrase / Plug-Unplug)

Use the Core API UI handler and register it before protected calls. Preserve request correlation, reply only to input requests, and cancel the selected operation when the user cancels. Device-only PIN and button prompts need no uiResponse.

Subscribe to DEVICE.CONNECT and DEVICE.DISCONNECT to refresh connection state. Do not log complete device or UI-event payloads.

Authorization (WebUSB Picker + Official Filter)


import { ONEKEY_WEBUSB_FILTER } from '@onekeyfe/hd-shared';
 
// Important: must be triggered by a user gesture (e.g., button click) or the browser will block it
await navigator.usb.requestDevice({ filters: ONEKEY_WEBUSB_FILTER });

Enumerate Devices and First Call


// 1) Enumerate
const list = await HardwareSDK.searchDevices();
if (!list.success) throw new Error(list.payload.error);
// Select explicitly in the application when more than one device is available.
if (list.payload.length !== 1) throw new Error('Select exactly one device before continuing');
const { connectId } = list.payload[0] ?? {};
if (!connectId) throw new Error("No device connection");
 
// 2) Confirm deviceId
const state = await HardwareSDK.getDeviceState(connectId);
if (!state.success) throw new Error(state.payload.error);
const resolvedDeviceId = state.payload.identity.deviceId;
if (!resolvedDeviceId) throw new Error("Device has no wallet identity");
 
// 3) Example: get a BTC address
const r = await HardwareSDK.btcGetAddress(connectId, resolvedDeviceId, {
  path: "m/44'/0'/0'/0/0",
  coin: 'btc',
  showOnOneKey: true,
  useEmptyPassphrase: true,
});
 
if (r.success) {
  console.log('BTC address:', r.payload.address);
} else {
  console.error('Error:', r.payload.error, r.payload.code);
}

Cleanup and Checklist

Dependency swap: remove @onekeyfe/hd-web-sdk, use @onekeyfe/hd-common-connect-sdk instead
Initialization changes:
- Old: env: 'web' + connectSrc: 'https://jssdk.onekey.so/.../'
- New: env: 'webusb' (no connectSrc)
Remove Bridge-only logic: e.g., checkBridgeStatus(), Bridge install/restart prompts
Bind UI_EVENT / DEVICE: ensure PIN/Passphrase and device plug/unplug events are handled
A new USB authorization requires requestDevice() from a user gesture. Previously authorized devices can be enumerated without opening the chooser again.
Compatibility tip: if navigator.usb is missing, ask users to switch to a WebUSB-capable browser

FAQ

No permission prompt on HTTP? → Serve over HTTPS
UI requests seem stuck? → Subscribe to UI_EVENT early and respond via uiResponse
Still using connectSrc or HdWebSdk.HardwareWebSdk? → Migrated to hd-common-connect-sdk; iframe is no longer needed
Called requestDevice outside a user gesture? → Chrome blocks it; must be triggered by a click or similar gesture