Introduction

Documentation destinée aux développeurs pour intégrer le matériel OneKey dans des applications web et natives.

Hardware SDK 1.2.x prend en charge Protocol V1 et Protocol V2 via la même API JavaScript. Vous débutez ? Commencez par Premiers pas.

Cette page est une vue d’ensemble — choisissez le paquet SDK adapté à votre plateforme et installez-le. Pour le parcours complet (recherche → événements → PIN/phrase secrète → premier appel de signature), les paramètres, les événements et la gestion des erreurs, consultez le Guide de l’API Core.

Choisissez votre transport

Les intégrations USB doivent utiliser @onekeyfe/hd-common-connect-sdk ; utilisez @onekeyfe/hd-web-sdk uniquement lorsque l’hôte impose une configuration iframe/plugin.

Méthodes de connexion

Guide des plateformes

Protocole de bas niveau et canaux personnalisés : Plugin de transport de bas niveau et protocole

Installer le SDK

Choisissez un point d’entrée selon l’environnement d’exécution :

# 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

Détails du transport :

• WebUSB : Guide WebUSB
• React Native BLE : Guide BLE
• Android / iOS / Flutter natif : transmettre les appels JS via des plugins de transport de bas niveau (voir les pages pour des exemples).
• Canal et protocole personnalisés : Plugin de transport de bas niveau et protocole

Initialiser le SDK

Utilisez la méthode d’initialisation correspondant à votre environnement — évitez de mélanger les points d’entrée SDK.

Web / ordinateur WebUSB

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

BLE React Native

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

Pont natif / bas niveau

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

Hôte iframe du plugin

Utilisez @onekeyfe/hd-web-sdk (plugin uniquement). L’hôte iframe par défaut du SDK est https://jssdk.onekey.so/<installed-package-version>/ depuis getSDKVersion(). Omettez connectSrc sauf si vous hébergez vous-même l’iframe.

Cette version de la documentation suit Hardware SDK 1.2.8-alpha.12. L’hôte iframe par défaut est https://jssdk.onekey.so/1.2.8-alpha.12/. Omettez connectSrc pour que le SDK utilise la version du paquet installé. Ne le remplacez que pour une iframe auto-hébergée, et faites-le correspondre à la version installée 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');

Étapes suivantes

Après le retour de HardwareSDK.init(...), suivez Premiers pas pour la première adresse, puis le Guide de l’API Core pour la suite du parcours :

• Matrice des appareils 1.2.0 : Appareils

• Quelles chaînes sur Pro 2 / Neo : Prise en charge des chaînes

• Protocol V1 ou V2 (détection automatique) : Protocole

• Ouvrir / reprendre un portefeuille : Sessions de portefeuille

• Sélecteur de transport et reconnexion : Transport · Reconnecter

• Micrologiciel V2 / V3 / V4 : Mise à jour du micrologiciel

• Cycle de vie standard (init → search → getDeviceState → subscribe → call + uiResponse → cleanup) : Guide de l’API Core → cycle de vie standard

• Paramètres partagés des méthodes d’adresse, de signature et d’appareil : Paramètres communs

• Référence des identifiants (connectId / deviceId / passphraseState / …) : Identifiants

• Parcours de saisie du PIN : Code PIN

• Parcours de phrase secrète / portefeuille caché : Phrase secrète

Compatibilité des appareils et transports

Prise en charge de Bluetooth, USB, Air-Gap et famille de protocole

Appareil	Protocole	Bluetooth	USB	Air-Gap
OneKey Classic 1s OneKey Classic 1s	V1	Pris en charge	Pris en charge	Non pris en charge
OneKey Classic 1s Pure Édition sans batterie	V1	Pris en charge	Pris en charge	Non pris en charge
OneKey Mini Portefeuille compact, USB uniquement	V1	Non pris en charge	Pris en charge	Non pris en charge
OneKey Touch Expérience entièrement tactile	V1	Pris en charge	Pris en charge	Non pris en charge
OneKey Pro Modèle haut de gamme avec sécurité par empreinte digitale	V1	Pris en charge	Pris en charge	Pris en charge
OneKey Pro 2 Édition professionnelle Protocol V2	V2	Pris en charge	Pris en charge	Pris en charge
OneKey Neo Édition compacte Protocol V2, sans caméra	V2	Pris en charge	Pris en charge	Non pris en charge

Mode Air-Gap : OneKey Pro et Pro 2 prennent en charge la signature isolée par QR codes — aucune connexion USB ou Bluetooth requise, avec vérification des détails sur l’appareil avant signature. Consultez Intégration Air-Gap pour plus de détails.

Paquets principaux

Paquet	Rôle	NPM	Version
@onekeyfe/hd-common-connect-sdk	Interface SDK unifiée pour Web/Natif ; point d’entrée recommandé pour les transports	npm
@onekeyfe/hd-ble-sdk	Pile BLE React Native pure (recommandée pour les projets RN)	npm
@onekeyfe/hd-transport-react-native	Effets de bord/pont du transport React Native	npm
@onekeyfe/hd-transport-web-device	Transport web pour l’accès aux appareils dans les contextes web	npm
@onekeyfe/hd-transport-emulator	Transport d’émulateur (développer et tester sans appareil physique)	npm
@onekeyfe/hd-transport-http	Transport de pont HTTP	npm
@onekeyfe/hd-transport-lowlevel	Contrat d’adaptateur hôte de bas niveau (pour les intégrations natives)	npm
@onekeyfe/hd-core	Événements, constantes et transmission des messages Core	npm
@onekeyfe/hd-shared	Utilitaires et types partagés	npm
@onekeyfe/hd-web-sdk	Enveloppe du SDK web (non recommandée ; privilégiez hd-common-connect-sdk)	npm

• Journal des modifications : versions 

Pour aller plus loin

• Transport de bas niveau et protocole de messages (pour le débogage ou les adaptateurs personnalisés) : Plugin de transport de bas niveau
• Migration depuis l’ancien parcours hd-web-sdk : Guide de migration

Assistance

Pour les utilisateurs : cette documentation s’adresse principalement aux développeurs. Si vous rencontrez des problèmes avec nos produits, consultez notre centre d’aide ou soumettez une demande d’assistance.

• Centre d’aide 
• Problèmes 

Dépôts associés

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

Essayer