Einführung

Entwicklerorientierte Dokumentation zur Integration von OneKey-Hardware in Web- und native Apps.

Hardware-SDK 1.2.x unterstützt Protocol V1 und Protocol V2 über dieselbe JavaScript-API. Neu hier? Beginnen Sie mit Erste Schritte.

Diese Seite ist die Orientierung — wählen Sie das passende SDK-Paket für Ihre Plattform und installieren Sie es. Den vollständigen Ablauf (Suchen → Ereignisse → PIN/Passphrase → erster Signieraufruf) sowie Parameter, Ereignisse und Fehlerbehandlung finden Sie in der Core-API-Anleitung.

Transport auswählen

USB-Integrationen sollten @onekeyfe/hd-common-connect-sdk verwenden. Verwenden Sie @onekeyfe/hd-web-sdk nur, wenn der Host eine Iframe-/Plugin-Einrichtung voraussetzt.

Verbindungsmethoden

Plattformanleitung

Protokoll auf niedriger Ebene und eigene Kanäle: Low-Level-Transport-Plugin & Protokoll

SDK installieren

Wählen Sie einen Einstieg nach Laufzeit:

# 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

Transportdetails:

• WebUSB: WebUSB-Anleitung
• React Native BLE: BLE-Anleitung
• Natives Android / iOS / Flutter: JS-Aufrufe über Low-Level-Transport-Plugins überbrücken (Beispiele auf den jeweiligen Seiten).
• Eigener Kanal & Protokoll: Low-Level-Transport-Plugin & Protokoll

SDK initialisieren

Verwenden Sie die zu Ihrer Laufzeit passende Initialisierungsmethode — mischen Sie keine SDK-Einstiege.

Web / Desktop-WebUSB

Verwenden Sie @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

Verwenden Sie @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');

Native Bridge / Low-Level

Verwenden Sie @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');

Plugin-Iframe-Host

Verwenden Sie @onekeyfe/hd-web-sdk (nur Plugin). Der standardmäßige Iframe-Host des SDKs ist https://jssdk.onekey.so/<installed-package-version>/ aus getSDKVersion(). Lassen Sie connectSrc weg, sofern Sie den Iframe nicht selbst hosten.

Dieser Dokumentationsstand bezieht sich auf Hardware SDK 1.2.8-alpha.12. Der standardmäßige Iframe-Host ist https://jssdk.onekey.so/1.2.8-alpha.12/. Lassen Sie connectSrc weg, damit das SDK die installierte Paketversion verwendet. Überschreiben Sie es nur für einen selbst gehosteten Iframe und stimmen Sie es auf die installierte @onekeyfe/hd-web-sdk-Version ab.

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

Nächste Schritte

Nachdem HardwareSDK.init(...) zurückkehrt, folgen Sie Erste Schritte für die erste Adresse und dann der Core-API-Anleitung für den restlichen Ablauf:

• Gerätematrix für 1.2.0: Geräte

• Welche Chains auf Pro 2 / Neo: Chain-Unterstützung

• Protocol V1 und V2 (automatisch erkannt): Protokoll

• Eine Wallet öffnen / fortsetzen: Wallet-Sitzungen

• Transportauswahl und Wiederverbindung: Transport · Wiederverbinden

• Firmware V2 / V3 / V4: Firmware-Update

• Standardlebenszyklus (init → search → getDeviceState → subscribe → call + uiResponse → cleanup): Core-API-Anleitung → Standardlebenszyklus

• Gemeinsame Parameter für Adress-, Signier- und Gerätemethoden: Gemeinsame Parameter

• Kennungsreferenz (connectId / deviceId / passphraseState / …): Kennungen

• PIN-Eingabeablauf: PIN-Code

• Passphrase-/Versteckte-Wallet-Ablauf: Passphrase

Geräte- und Transportkompatibilität

Unterstützungsstatus für Bluetooth, USB, Air-Gap und Protokollfamilie

Gerät	Protokoll	Bluetooth	USB	Air-Gap
OneKey Classic 1s OneKey Classic 1s	V1	Unterstützt	Unterstützt	Nicht unterstützt
OneKey Classic 1s Pure Edition ohne Akku	V1	Unterstützt	Unterstützt	Nicht unterstützt
OneKey Mini Kompakte Wallet nur mit USB	V1	Nicht unterstützt	Unterstützt	Nicht unterstützt
OneKey Touch Umfassende Touchscreen-Bedienung	V1	Unterstützt	Unterstützt	Nicht unterstützt
OneKey Pro Premium mit Fingerabdruckschutz	V1	Unterstützt	Unterstützt	Unterstützt
OneKey Pro 2 Professionelle Edition mit Protocol V2	V2	Unterstützt	Unterstützt	Unterstützt
OneKey Neo Kompakte Edition mit Protocol V2, ohne Kamera	V2	Unterstützt	Unterstützt	Nicht unterstützt

Air-Gap-Modus: OneKey Pro und Pro 2 unterstützen Air-Gap-Signieren per QR-Code — ohne USB- oder Bluetooth-Verbindung; Details werden vor dem Signieren auf dem Gerät geprüft. Siehe Air-Gap-Integration für Details.

Core-Pakete

Paket	Zweck	NPM	Version
@onekeyfe/hd-common-connect-sdk	Einheitliche SDK-Oberfläche für Web/Native; empfohlener Einstieg für Transporte	npm
@onekeyfe/hd-ble-sdk	Reiner React-Native-BLE-Stack (für RN-Projekte empfohlen)	npm
@onekeyfe/hd-transport-react-native	React-Native-Transport-Nebenwirkungen/Bridge	npm
@onekeyfe/hd-transport-web-device	Webtransport für den Gerätezugriff in Webkontexten	npm
@onekeyfe/hd-transport-emulator	Emulatortransport (ohne physisches Gerät entwickeln und testen)	npm
@onekeyfe/hd-transport-http	HTTP-Bridge-Transport	npm
@onekeyfe/hd-transport-lowlevel	Schnittstellenvertrag des Low-Level-Host-Adapters (für native Integrationen)	npm
@onekeyfe/hd-core	Core-Ereignisse, Konstanten, Nachrichtenanbindung	npm
@onekeyfe/hd-shared	Gemeinsame Hilfsfunktionen und Typen	npm
@onekeyfe/hd-web-sdk	Web-SDK-Wrapper (nicht empfohlen; hd-common-connect-sdk bevorzugen)	npm

• Änderungsprotokoll: Releases 

Weiterführende Informationen

• Transport und Nachrichtenprotokoll auf niedriger Ebene (zum Debuggen oder für eigene Adapter): Low-Level-Transport-Plugin
• Migration vom älteren hd-web-sdk-Ablauf: Migrationsanleitung

Support

Für Nutzer: Diese Dokumentation richtet sich hauptsächlich an Entwickler. Bei Problemen mit unseren Produkten besuchen Sie bitte unser Hilfe-Center oder reichen Sie ein Support-Ticket ein.

• Hilfe-Center 
• Issues 

Verwandte Repositorys

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

Ausprobieren