はじめに

Web アプリとネイティブアプリに OneKey ハードウェアを統合する開発者向けドキュメント。

Hardware SDK 1.2.x は同じ JavaScript API で Protocol V1 と Protocol V2 に対応します。初めての方は次から始めてください: はじめに.

このページは 導入案内 — プラットフォームに適した SDK パッケージを選んでインストールします。一連の手順 (検索 → イベント → PIN/パスフレーズ → 最初の署名呼び出し) と、パラメーター、イベント、エラー処理は次を参照してください: Core API ガイド.

トランスポートを選択

USB 統合では @onekeyfe/hd-common-connect-sdk を使用してください。@onekeyfe/hd-web-sdk は、ホストが iframe/プラグイン構成を要求する場合にのみ使用します。

接続方法

プラットフォームガイド

低レベルプロトコルとカスタムチャネル: 低レベルトランスポートプラグインとプロトコル

SDK をインストール

実行環境に応じて 1 つのエントリーを選択します:

# 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

トランスポートの詳細:

• WebUSB: WebUSB ガイド
• React Native BLE: BLE ガイド
• ネイティブ Android / iOS / Flutter: 低レベルトランスポートプラグインを通じて JS 呼び出しを橋渡しします (各ページの例を参照)。
• カスタムチャネルとプロトコル: 低レベルトランスポートプラグインとプロトコル

SDK を初期化

実行環境に対応する初期化メソッドを使用し、SDK エントリーを混在させないでください。

Web / デスクトップ WebUSB

@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

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

ネイティブブリッジ / 低レベル

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

プラグインの iframe ホスト

@onekeyfe/hd-web-sdk を使用します (プラグインのみ)。SDK のデフォルトの iframe ホストは、getSDKVersion() から取得したバージョンを使う https://jssdk.onekey.so/<installed-package-version>/ です。iframe を自分でホストする場合を除き、connectSrc を省略します。

このドキュメントのビルドは次の Hardware SDK に対応しています: 1.2.8-alpha.12. デフォルトの iframe ホストは https://jssdk.onekey.so/1.2.8-alpha.12/. connectSrc を省略すると、SDK はインストール済みパッケージのバージョンを使います。iframe を自分でホストする場合のみ上書きし、インストール済みの @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');

次の手順

HardwareSDK.init(...) が返ったら、はじめにに従って最初のアドレスを取得します。続いて Core API ガイドで残りのフローを進めます:

• 1.2.0 のデバイス対応表: デバイス

• Pro 2 / Neo の対応チェーン: 対応チェーン

• Protocol V1 と V2 (自動検出): プロトコル

• ウォレットを開く / 再開: ウォレットセッション

• トランスポートの選択と再接続: トランスポート · 再接続

• ファームウェア V2 / V3 / V4: ファームウェア更新

• 標準ライフサイクル (init → search → getDeviceState → subscribe → call + uiResponse → cleanup): Core API ガイド → 標準ライフサイクル

• アドレス取得、署名、デバイスメソッドの共通パラメーター: 共通パラメーター

• 識別子のリファレンス (connectId / deviceId / passphraseState / …): 識別子

• PIN 入力フロー: PIN コード

• パスフレーズ / 隠しウォレットのフロー: パスフレーズ

デバイスとトランスポートの互換性

Bluetooth、USB、Air-Gap、プロトコルファミリーの対応状況

デバイス	プロトコル	Bluetooth	USB	Air-Gap
OneKey Classic 1s OneKey Classic 1s	V1	対応	対応	未対応
OneKey Classic 1s Pure バッテリー非搭載モデル	V1	対応	対応	未対応
OneKey Mini コンパクトな USB 専用ウォレット	V1	未対応	対応	未対応
OneKey Touch 全面タッチスクリーンの操作体験	V1	対応	対応	未対応
OneKey Pro 指紋認証で保護するプレミアムモデル	V1	対応	対応	対応
OneKey Pro 2 Protocol V2 プロフェッショナルモデル	V2	対応	対応	対応
OneKey Neo Protocol V2 のコンパクトモデル、カメラなし	V2	対応	対応	未対応

Air-Gap モード: OneKey Pro と Pro 2 は QR コードによるエアギャップ署名に対応します。USB や Bluetooth の接続は不要で、署名前にデバイス上で詳細を確認します。参照: Air-Gap 統合 で詳細を確認してください。

主要パッケージ

パッケージ	目的	NPM	バージョン
@onekeyfe/hd-common-connect-sdk	Web/Native 共通の SDK インターフェース。トランスポート利用の推奨エントリー	npm
@onekeyfe/hd-ble-sdk	純粋な React Native BLE スタック (RN プロジェクトに推奨)	npm
@onekeyfe/hd-transport-react-native	React Native トランスポートの副作用/ブリッジ	npm
@onekeyfe/hd-transport-web-device	Web 環境でデバイスにアクセスする Web トランスポート	npm
@onekeyfe/hd-transport-emulator	エミュレータートランスポート (実機なしで開発・テスト)	npm
@onekeyfe/hd-transport-http	HTTP ブリッジトランスポート	npm
@onekeyfe/hd-transport-lowlevel	低レベルのホストアダプター仕様 (ネイティブ統合用)	npm
@onekeyfe/hd-core	Core イベント、定数、メッセージの接続	npm
@onekeyfe/hd-shared	共通ユーティリティと型	npm
@onekeyfe/hd-web-sdk	Web SDK ラッパー (非推奨。hd-common-connect-sdk を優先)	npm

• 変更履歴: リリース 

関連ドキュメント

• 低レベルトランスポートとメッセージプロトコル (デバッグや独自アダプター用): 低レベルトランスポートプラグイン
• 従来の hd-web-sdk フローから移行する場合: 移行ガイド

サポート

ユーザーの方へ: このドキュメントは主に開発者向けです。製品の使用中に問題が発生した場合は、ヘルプセンターを参照するか、サポートチケットを送信してください。

• ヘルプセンター 
• 課題 

関連リポジトリ

• OneKey アプリ (app-monorepo) 
• OneKey ファームウェア 
• OneKey Hardware JS SDK 

試してみる