Auf Hardware SDK 1.2 aktualisieren

Aktualisieren Sie eine bestehende Integration von Hardware SDK 1.1.x auf 1.2.x. Behalten Sie einen SDK-Einstiegspunkt; Protocol V2 erfordert kein zweites SDK. Neue Projekte beginnen mit Erste Schritte.

Für Protocol V2 erforderlich: Ersetzen Sie V1-exklusive Geräteabfragen und prüfen Sie Geräte-, Firmware- und Protokollunterstützung jeder Methode. Empfohlen: Verwenden Sie im neuen Code eine explizite Wallet-Auswahl. Kompatibilität: Bestehende unterstützte Chain-Aufrufe können bleiben; getPassphraseState bleibt eine veraltete Kompatibilitätshilfe für beide Protokolle. Bei Bedarf: Bridge durch WebUSB ersetzen, den SDK-Einstiegspunkt wechseln oder Firmware-Updates implementieren sind eigenständige Entscheidungen.

Was gleich bleibt

• Ergebnisse bleiben { success, payload }; prüfen Sie success, bevor Sie ein erfolgreiches Ergebnis verwenden. Fehler enthalten payload.error sowie, falls vorhanden, payload.code.
• Chain-Methoden wie evmGetAddress und btcSignTransaction behalten die öffentliche Aufrufform HardwareSDK.method(connectId, deviceId?, params). Ihre Verfügbarkeit hängt weiterhin von Gerät und Firmware ab.
• init({ env }) wählt den Transport, nicht Protocol V1 oder V2. keepSession hält weiterhin den Transport; es wählt keine Wallet.

Upgrade

Behalten Sie das zu Ihrer Laufzeit passende Einstiegspaket. Bei einer bestehenden common-connect-Integration wählt der folgende Befehl die 1.2-Linie und speichert die aufgelöste Version exakt; ersetzen Sie 1.2 für eine reproduzierbare Veröffentlichung durch die vollständig getestete Versionsnummer.

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

Fixieren Sie alle direkt installierten @onekeyfe/hd-*-Pakete auf dieselbe exakte Version, einschließlich gemeinsamer Typen und Transportpakete. Committen Sie die Lockdatei und prüfen Sie den aufgelösten Abhängigkeitsbaum. Wählen Sie für Vorabtests ausdrücklich eine Alpha-Version. Eine 1.2.x-Version garantiert nicht alle Methoden späterer Patches: Prüfen Sie die minimale SDK- und Firmware-Version jeder API.

Lassen Sie bei @onekeyfe/hd-web-sdk den Parameter connectSrc weg, um die standardmäßige iframe-URL des installierten Pakets zu verwenden. Bei einer eigenen URL oder eigenem Hosting müssen passende kompatible iframe-Dateien bereitstehen; prüfen Sie URL, CSP und erfolgreiche Initialisierung. Eine npm-Veröffentlichung beweist nicht, dass das gehostete iframe verfügbar ist. Veröffentlichen und restaurieren Sie Paket und iframe gemeinsam.

Laden Sie @onekeyfe/hd-web-sdk und @onekeyfe/hd-common-connect-sdk nicht gemeinsam in einer Laufzeit. Native Integrationen müssen auch das installierte Transport-Plugin und Berechtigungen mit der gewählten SDK-Version prüfen; siehe Erste Schritte.

Diese APIs ersetzen

Es gibt kein openWalletSession({ mode: 'resume-hidden' }). Bestehende versteckte Bindungen werden in späteren Methoden mit passphraseState wieder aufgenommen.

1. Gerätestatus

1.1.x

const features = await HardwareSDK.getFeatures(connectId);
if (!features.success) throw new Error(features.payload.error);
const deviceId = features.payload.device_id;

1.2.x

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

Standardmäßig aktualisiert scope: 'runtime' den Status; scope: 'settings' Status und Einstellungen; scope: 'firmware' Status, Identität, Versionen und Verifikation. Zurückgegeben wird immer ein vollständiger Zustand, nicht nur der aktualisierte Teil. Felder können im aktuellen Modus fehlen: Behalten Sie null bei, statt es in false oder 0.0.0 umzuwandeln. Einstellungsabfragen werden im V2-Bootloader-/Romloader-Modus nicht unterstützt.

Prüfen Sie den Erfolg von searchDevices, bevor Sie die Liste lesen. connectId bezeichnet die aktuelle Transportverbindung und kann sich nach Wiederverbindung ändern. Ersetzen Sie eine fehlende deviceId nicht durch eine Seriennummer und verwenden Sie die Hardware-Seriennummer nicht als Wallet-Bindung. Siehe Identifikatoren und Gerätezustand.

2. Wallet-Sitzung

1.1.x — versteckte Wallet auswählen und ihren Fingerabdruck weitergeben:

const ps = await HardwareSDK.getPassphraseState(connectId, {
  initSession: true,
});
if (!ps.success) throw new Error(ps.payload.error);
if (typeof ps.payload !== 'string' || !ps.payload) {
  throw new Error('No hidden wallet fingerprint');
}
const address = await HardwareSDK.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/0'/0/0",
  passphraseState: ps.payload,
});
if (!address.success) throw new Error(address.payload.error);

1.2.x — führen Sie entsprechend der Benutzerauswahl einen der folgenden Abläufe aus. Führen Sie nicht beide nacheinander aus.

Standard-Wallet

import { OpenWalletSessionMode } from '@onekeyfe/hd-core';
 
const opened = await HardwareSDK.openWalletSession(connectId, {
  mode: OpenWalletSessionMode.Standard,
});
if (!opened.success) throw new Error(opened.payload.error);
if (opened.payload.walletType !== 'standard') {
  throw new Error('A standard wallet was not opened');
}
const address = await HardwareSDK.evmGetAddress(connectId, opened.payload.deviceId, {
  path: "m/44'/60'/0'/0/0",
  useEmptyPassphrase: true,
});
if (!address.success) throw new Error(address.payload.error);

Versteckte Wallet

import { OpenWalletSessionMode } from '@onekeyfe/hd-core';
 
const opened = await HardwareSDK.openWalletSession(connectId, {
  mode: OpenWalletSessionMode.SelectHidden,
});
if (!opened.success) throw new Error(opened.payload.error);
if (opened.payload.walletType !== 'hidden' || !opened.payload.passphraseState) {
  throw new Error('A hidden wallet was not opened');
}
const binding = opened.payload;
const address = await HardwareSDK.evmGetAddress(connectId, binding.deviceId, {
  path: "m/44'/60'/0'/0/0",
  passphraseState: binding.passphraseState,
});
if (!address.success) throw new Error(address.payload.error);

Speichern Sie die zurückgegebenen walletType, deviceId und passphraseState erst nach Prüfung von Erfolg und Wallet-Typ. Eine Standard-Wallet hat den Fingerabdruck null. Bei V1 ohne Passphrase-Schutz kann die Auswahl einer versteckten Wallet eine Standard-Wallet liefern; speichern Sie diese nicht als versteckt.

Übergeben Sie die alten Parameter useEmptyPassphrase, initSession, deviceId oder passphraseState nicht an openWalletSession, auch keine übernommenen Standardwerte mit false. Spätere Adress-/Signaturaufrufe verwenden useEmptyPassphrase: true für die Standard-Wallet oder den gespeicherten passphraseState für die versteckte Wallet. Ohne versteckten Fingerabdruck kann der Aufruf ohne Fehler auf der Standard-Wallet erfolgreich sein.

Öffnen Sie die Wallet-Auswahl nicht vor jeder Methode oder automatisch nach Wiederverbindung. Verwenden Sie die Bindung erneut; stoppen Sie bei fehlgeschlagener Identitäts- oder Fingerabdruckprüfung und verlangen Sie eine ausdrückliche Auswahl. Überschreiben Sie die Bindung nicht durch ein neu verbundenes Gerät. Siehe Wallet-Sitzungen.

UI, Abbruch und Wiederverbindung

Die Methoden-Promise liefert das endgültige Ergebnis. Klassifizieren Sie Fehler mit payload.code statt durch lokalisierten Text; unterscheiden Sie ungültige Parameter, nicht unterstützte Methoden, Wallet-Abweichungen, Abbruch und Transportfehler.

UI_EVENT-Listener erhalten eine Nachricht mit Typ und Inhalt. DEVICE.STATE-Listener erhalten den Zustandsevent-Inhalt direkt, einschließlich connectId, state und revision; behandeln Sie beide Strukturen unterschiedlich. Registrieren Sie Listener einmal und entfernen Sie sie beim Abbau der Integration.

Führen Sie Aufrufe pro Gerät und Host-PIN-/Passphrase-Dialoge über Geräte hinweg seriell aus. Die aktuellen öffentlichen Einstiegspunkte leiten aus uiResponse nur type und payload weiter; verlassen Sie sich nicht auf die Weiterleitung von Korrelationsmetadaten auf oberster Ebene. Entwerten Sie alte Dialog-Callbacks bei Schließen, Abbruch und Verbindungsverlust, damit sie keine spätere Anfrage beantworten.

Brechen Sie die aktive Operation mit HardwareSDK.cancel(connectId) ab und respektieren Sie den Benutzerabbruch. Nach Verbindungsverlust suchen Sie das Gerät erneut, erhalten die aktuelle Verbindung, lesen den Zustand und nutzen die geprüfte Wallet-Bindung. Signieren, Löschen und Firmware-Updates dürfen nicht automatisch wiederholt werden. Ein gewöhnlicher Verbindungsverlust erfordert kein dispose; nach expliziter Freigabe des SDK ist vor weiteren Aufrufen eine neue Initialisierung nötig. Siehe Core-API-Leitfaden und Wiederverbindung.

3. Protocol V1 und V2

Classic / Mini / Touch / Pro verwenden Protocol V1; Pro 2 / Neo verwenden Protocol V2. Das SDK erkennt das Protokoll durch eine direkte Abfrage. Leiten Sie es nicht aus USB-PID, BLE-Namen oder Gehäuse ab.

Lassen Sie normalerweise die Erkennung entscheiden. Wenn Sie connectProtocol übergeben, ist dies eine strikte Vorgabe: Abweichungen werden abgelehnt. SDK-Version, Protokollunterstützung und minimale Gerätefirmware sind getrennte Prüfungen; prüfen Sie vor Aktivierung einer Methode die API-Unterstützungstabelle.

V1-exklusive Chains (Stellar, Alephium, Nexa, Dynex, Nervos, SCDO, Benfen und die Neo-Chain) werden auf Pro 2 / Neo nicht unterstützt. Der Gerätename Neo bedeutet keine Unterstützung der Neo-Chain. Siehe Protokoll und Chain-Unterstützung.

4. Firmware

Wenn Ihre Integration Firmware verwaltet, passen Sie auch die Auswertung der Release-Prüfung an: Releases für das V2-Protokoll können Zielkomponenten und ein Ressourcenarchiv enthalten. Gehen Sie nicht von einer einzigen alten Binärdatei oder immer vorhandener URL/Fingerabdruck aus. Verwenden Sie zum Modell passende Dateien und den Vertrag der gewählten Update-API.

Eine Bestätigung oder Fortschrittsmeldung beweist keine Installation. Verbinden Sie sich nach dem Neustart erneut und lesen Sie scope: 'firmware', um die installierten Versionen zu prüfen. Behalten Sie benötigte keepSession-Transporthalte bei und wiederholen Sie Updates nach Verbindungsverlust niemals automatisch. Siehe Firmware-Update.

5. Transport

Ein Upgrade von 1.1.x auf 1.2.x verlangt keinen Wechsel eines funktionierenden Transports. Wenn Sie auch Bridge (env: 'web' + checkBridgeStatus) auf WebUSB umstellen, folgen Sie dem eigenen Leitfaden:

• Bridge → common-connect WebUSB
• Bridge → iframe WebUSB

WebUSB benötigt einen sicheren Kontext und eine Benutzeraktion für die Berechtigungsauswahl. BLE benötigt die Bluetooth-Berechtigungen des Betriebssystems. Testen Sie im tatsächlich ausgelieferten Browser, Electron oder nativen System.

Checkliste

1. Wählen Sie eine exakte Version, gleichen Sie SDK-Abhängigkeiten und iframe-Dateien ab und sichern Sie die bisherige Lockdatei und Veröffentlichung.
2. Passen Sie Zustandsabfragen und Nullwerte an; ersetzen Sie alte Abfragen, wenn V2 benötigt wird.
3. Aktualisieren Sie die Wallet-Auswahl und speichern Sie geprüfte Bindungen; Transportverbindungen und Firmware-Sitzungs-IDs sind keine Wallet-Identität.
4. Aktualisieren Sie Eingaben/Benachrichtigungen, Abbruch und Wiederverbindung; serialisieren Sie Geräteaufrufe und Host-Dialoge.
5. Prüfen Sie Protokoll-, Chain- und Firmware-Unterstützung; migrieren Sie Updates nur, wenn Ihre Integration diese verwaltet.

Führen Sie vor Veröffentlichung diese Fälle in jeder unterstützten Laufzeit aus. Hardwarefälle benötigen echte Geräte; ein erfolgreicher Dokumentationsbuild ist kein Hardwaretest.

Vergleichen Sie bekannte Wallet-Adressen und unterstützte Signaturergebnisse mit Ihrer 1.1.x-Basis; prüfen Sie Fehler anhand des Codes. PINs, Passphrases, abgeleitete Geheimnisse oder private Daten gehören weder in Logs noch in Testdaten.

Zur alten Version zurückkehren

Bewahren Sie bisherige exakte Abhängigkeiten, Lockdatei, iframe-Dateien und Laufzeitkonfiguration als eine getestete Veröffentlichung auf. Stellen Sie diese gemeinsam wieder her; mischen Sie kein 1.1.x-Einstiegspaket mit 1.2.x-Dateien oder Typen.

Deaktivieren Sie neu aktivierte V2-exklusive Integrationen, wenn Sie zur 1.1.x-Basis zurückkehren. Ein SDK-Downgrade ist kein Firmware-Downgrade. Erhalten Sie gespeicherte Wallet-Bindungen als Daten, prüfen Sie sie aber mit der wiederhergestellten Integration und verlangen Sie bei fehlender Verifizierbarkeit eine Benutzerauswahl. Wechseln Sie nicht automatisch zur Standard-Wallet und wiederholen Sie keine abgebrochenen Operationen.

Weiter

• Erste Schritte
• Core-API-Leitfaden
• Wallet-Sitzungen
• Wiederverbindung und Freigabe