Skip to Content
HardwareTransportReact Native BLE
On this page

React Native BLE (hd-ble-sdk)

Note: Demo: React Native / Expo example → react-native-demo 

This guide shows how to use the pure React Native BLE stack with @onekeyfe/hd-ble-sdk and @onekeyfe/hd-transport-react-native. No WebView or low-level adapter is required. The chain API usage stays the same as in Quick Start.

Install

We recommend installing the RN-native dependencies at the app layer so that autolinking includes the native modules in your Dev Client build:

npm i @onekeyfe/hd-ble-sdk @onekeyfe/hd-transport-react-native \
      @onekeyfe/react-native-ble-utils react-native-ble-plx \
      buffer process react-native-get-random-values react-native-url-polyfill

In your app entry (e.g., index.js or App.tsx):

// Polyfills (adjust to your project needs)
import 'react-native-get-random-values';
import 'react-native-url-polyfill/auto';
// @ts-ignore
global.Buffer = global.Buffer || require('buffer').Buffer;
// @ts-ignore
global.process = global.process || require('process');
 
// Register RN transport side-effects before SDK init
import '@onekeyfe/hd-transport-react-native';
 
import HardwareSDK from '@onekeyfe/hd-ble-sdk';

Android setup

For a BLE client that does not derive location, use the following permission declarations. Set neverForLocation only when that assertion is true for your app:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30"/>
 
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>

On Android 12+, request BLUETOOTH_SCAN and BLUETOOTH_CONNECT at runtime. Location access depends on the target SDK, whether the app derives location, and the BLE library configuration; it is not universally required on Android 12+. On older Android versions, use the applicable legacy/location permissions. See the Android permission guide .

iOS setup

Add to Info.plist:

  • NSBluetoothAlwaysUsageDescription (required)
  • Optionally NSBluetoothPeripheralUsageDescription for older iOS versions
  • If your app uses the camera (e.g. QR scanning), add NSCameraUsageDescription

If using Expo, you can declare these in app.json under expo.ios.infoPlist and expo.android.permissions.

Metro config (polyfills & exports)

If Metro reports missing Node core APIs, map only the modules your dependency graph requires. Install every package referenced by require.resolve before using a mapping. Merge these entries into your existing resolver configuration; do not replace framework defaults. The following is an optional mapping fragment, not a complete Metro configuration:

// metro.config.js
config.resolver.extraNodeModules = {
  buffer: require.resolve('buffer/'),
  crypto: require.resolve('crypto-browserify'),
  stream: require.resolve('stream-browserify'),
  process: require.resolve('process/browser'),
  events: require.resolve('events/'),
  http: require.resolve('http-browserify'),
  https: require.resolve('https-browserify'),
  zlib: require.resolve('browserify-zlib'),
  util: require.resolve('util/'),
  url: require.resolve('url/'),
  path: require.resolve('path-browserify'),
};
config.resolver.unstable_enablePackageExports = true;

Build Dev Client (real devices)

Expo Go does not include your native BLE modules. Build a Dev Client:

# iOS
expo run:ios --device
 
# Android
expo run:android --device
 
# Start bundler for Dev Client
expo start --dev-client -c

Initialize and subscribe to events

export async function setupBle() {
  const initialized = await HardwareSDK.init({
    env: 'react-native',                 // React Native BLE transport
    debug: false,
    fetchConfig: true,
  });
  if (!initialized) throw new Error('SDK initialization failed');
 
  // Subscribe to UI events (PIN / Passphrase / confirmations)
  // import { UI_EVENT, UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hd-core'
  // HardwareSDK.on(UI_EVENT, (msg) => { /* open dialogs and reply via HardwareSDK.uiResponse(...) */ });
}

Discover devices and identify device_id

const devices = await HardwareSDK.searchDevices();
if (!devices.success) throw new Error(devices.payload.error);
 
// BLE returns id + name; read identity via getDeviceState
// Select explicitly in the application when more than one device is available.
if (devices.payload.length !== 1) throw new Error('Select exactly one device before continuing');
const candidate = devices.payload[0];
const connectId = candidate?.connectId;
if (!connectId) throw new Error("No device connection");
 
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");

Persist connectId and deviceId (most chain APIs require both).

First call example (BTC address)

const res = await HardwareSDK.btcGetAddress(connectId, deviceId, {
  path: "m/44'/0'/0'/0/0",
  coin: 'btc',
  showOnOneKey: true,
  useEmptyPassphrase: true,
});
 
if (res.success) {
  console.log('BTC address:', res.payload.address);
} else {
  console.error('Error:', res.payload.error, res.payload.code);
}

Tips

  • Always subscribe early to UI_EVENT so PIN/Passphrase/confirmations do not stall requests. See Config Event.
  • Keep BLE permissions in sync with the OS version. Test on physical devices.
  • For additional examples, check: react-native-demo 

Continue

Last updated on
WebUSBNative BLE