react-native-ble-manager

The example application uses Expo to simplify management. To set up the environment and generate the necessary native projects, install the dependencies and run the Expo prebuild command.

1. Install dependencies: npm i
2. Generate native projects: npx expo prebuild

Since React Native version 0.76, events are handled via specific methods on the BleManager instance that return a listener object. To prevent memory leaks, you must call .remove() on the returned listener when the component unmounts.

Example of subscribing to the onStopScan event:

useEffect(() => {
  const onStopListener = BleManager.onStopScan((args) => {
    // Scanning is stopped args.status
  });

  return () => {
    onStopListener.remove();
  };
    
}, []);

To use BLE on Android, you must update your android/app/src/main/AndroidManifest.xml file with the necessary permissions.

Important Notes:

• For Android 12+ (API 31+), you must include BLUETOOTH_SCAN, BLUETOOTH_CONNECT, and/or BLUETOOTH_ADVERTISE.
• If your app uses Bluetooth scan results to derive physical location, do not use the neverForLocation flag on BLUETOOTH_SCAN.
• If you are working with Beacons, remove android:usesPermissionFlags="neverForLocation".
• If you need communication while the app is in the background, you must also add the ACCESS_BACKGROUND_LOCATION permission.

Update your Info.plist file to include the required usage descriptions for Bluetooth:

• iOS 13 and higher: Add the NSBluetoothAlwaysUsageDescription key.
• Earlier than iOS 13: Add the NSBluetoothPeripheralUsageDescription key.
• Background Usage: To allow Bluetooth communication in the background, add central-peripheral to the UIBackgroundModes key.

To use react-native-ble-manager in an Expo project, you must use a development build. Standard Expo Go does not support the native modules required by this library.

Starting with version 12.x, the library supports the new React Native architecture. For versions 12.1.x and later, you can use the Expo config plugin to automate native configuration by adding it to your app.json or app.config.js file.

{
    ...
    "plugins" : [
        ...
        ["react-native-ble-manager", { options }]
    ],
}

To generate Android code via codegen, you must use a React Native project (the provided example folder is used here).

1. In the example folder, generate the Android project from Expo: npx expo prebuild --platform android.
2. In the example/android folder, run the codegen command: ./gradlew generateCodegenArtifactsFromSchema.

Troubleshooting: If you encounter issues with the Gradle cache, run:

cd android && ./gradlew --stop && rm -rf ~/.gradle/caches

After running npx expo prebuild, you can run the example application on iOS or Android using the following commands:

For iOS: npx expo run:ios

For Android: npx expo run:android

# iOS
npx expo run:ios

# Android
npx expo run:android

To generate iOS code via codegen, use the example folder.

1. In the example folder, generate the iOS project from Expo: npx expo prebuild --platform ios.
2. Codegen runs during the first build. If you need to trigger it again, run pod install inside the ios folder.

Before using react-native-ble-manager, ensure your environment meets the following requirements:

React Native Version Compatibility

• RN 0.76+: Only the New Architecture is supported.
• RN 0.60 - 0.75: Supported up to version 11.5.X.
• RN 0.40 - 0.59: Supported up to version 6.7.X.
• RN 0.30 - 0.39: Supported up to version 2.4.3.

Supported Operating Systems

• iOS: 15.1+
• Android: API level 23+

By default, the library code is copied to the node_modules folder. If you want to modify the react-native-ble-manager library code directly and see changes reflected in the created example projects, use npm link to create a symbolic link.

npm link react-native-ble-manager