cordova-plugin-ble-central - npm Package Compare versions

Comparing version 1.6.3 to 1.7.0-alpha.1

package.json

 {
   "name": "cordova-plugin-ble-central",
-  "version": "1.6.3",
+  "version": "1.7.0-alpha.1",
   "description": "Bluetooth Low Energy (BLE) Central Plugin",
@@ -5,0 +5,0 @@ "cordova": {

README.md

@@ -35,32 +35,55 @@ # Bluetooth Low Energy (BLE) Central Plugin for Apache Cordova
 
-### Cordova
+## Capacitor
 
-    $ cordova plugin add cordova-plugin-ble-central
+    $ npm install cordova-plugin-ble-central
+    $ npx cap sync
 
-It's recommended to always use the latest cordova and cordova platform packages in order to enusre correct function. This plugin generally best supports the following platforms and version ranges:
+The plugin can be further configured via the cordova preferences section of the [capacitor config file](https://capacitorjs.com/docs/cordova/migrating-from-cordova-to-capacitor#cordova-plugin-preferences):
 
-| cordova | cordova-ios | cordova-android | cordova-browser |
-| ------- | ----------- | --------------- | --------------- |
-| 10+     | 6.2.0+      | 10.0+           | not tested      |
+```
+const config = {
+  ...
+  cordova: {
+    preferences: {
+      ...
+      bluetooth_restore_state: "true",
+      accessBackgroundLocation: "false",
+    },
+  }
+}
+```
 
+-   `bluetooth_restore_state`: [**iOS**] Enable Bluetooth state restoration, allowing an app to be woken up to receive scan results and peripheral notifications. This is needed for background scanning support. See [iOS restore state](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html#//apple_ref/doc/uid/TP40013257-CH7-SW13). For more information about background operation with this plugin, see [Background Scanning and Notifications on iOS](#background-scanning-and-notifications-on-ios).
+
+-   `accessBackgroundLocation`: [**Android**] Tells the plugin to request the `ACCESS_BACKGROUND_LOCATION` permission on Android 10 & Android 11 in order for scanning to function when the app is not visible.
+
 ### iOS
 
-For iOS, apps will crash unless they include usage description keys for the types of data they access. Applications targeting iOS 13 and later, define [NSBluetoothAlwaysUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nsbluetoothalwaysusagedescription?language=objc) to tell the user why the application needs Bluetooth. For apps with a deployment target earlier than iOS 13, add [NSBluetoothPeripheralUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nsbluetoothperipheralusagedescription?language=objc). Both of these keys can be set when installing the plugin by passing the BLUETOOTH_USAGE_DESCRIPTION variable.
+After installation, the following additions should be made to the app's `Info.plist`
 
-    $ cordova plugin add cordova-plugin-ble-central --variable BLUETOOTH_USAGE_DESCRIPTION="Your description here"
+-   Set [NSBluetoothAlwaysUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nsbluetoothalwaysusagedescription?language=objc) to a descriptive text, to be shown to the user on first access to the Bluetooth adapter. **If this is not defined the app will crash**.
+-   _(Optional)_ Add `bluetooth-central` to [UIBackgroundModes](https://developer.apple.com/documentation/bundleresources/information_property_list/uibackgroundmodes?language=objc) to enable background receipt of scan information and BLE notifications
 
-See Apple's documentation about [Protected Resources](https://developer.apple.com/documentation/bundleresources/information_property_list/protected_resources) for more details. If your app needs other permissions like location, try the [cordova-custom-config plugin](https://github.com/don/cordova-plugin-ble-central/issues/700#issuecomment-538312656).
+## Cordova
 
-It is possible to delay the initialization of the plugin on iOS. Normally the Bluetooth permission dialog is shown when the app loads for the first time. Delaying the initialization of the plugin shows the permission dialog the first time the Bluetooth API is called. Set `IOS_INIT_ON_LOAD` to false when installing.
+`$ cordova plugin add cordova-plugin-ble-central --variable BLUETOOTH_USAGE_DESCRIPTION="Your description here" --variable IOS_INIT_ON_LOAD=true|false --variable BLUETOOTH_RESTORE_STATE=true|false --variable ACCESS_BACKGROUND_LOCATION=true|false`
 
-    --variable IOS_INIT_ON_LOAD=false
+It's recommended to always use the latest cordova and cordova platform packages in order to ensure correct function. This plugin generally best supports the following platforms and version ranges:
 
-If background scanning and operation is required, the [iOS restore state](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html#//apple_ref/doc/uid/TP40013257-CH7-SW13) should be enabled:
+| cordova | cordova-ios | cordova-android | cordova-browser |
+| ------- | ----------- | --------------- | --------------- |
+| 10+     | 6.2.0+      | 10.0+           | not tested      |
 
-    --variable BLUETOOTH_RESTORE_STATE=true
+All variables can be modified after installation by updating the values in `package.json`.
 
-For more information about background operation, see [Background Scanning and Notifications on iOS](#background-scanning-and-notifications-on-ios).
+-   `BLUETOOTH_USAGE_DESCRIPTION`: [**iOS**] defines the values for [NSBluetoothAlwaysUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nsbluetoothalwaysusagedescription?language=objc).
 
-### Android
+-   `IOS_INIT_ON_LOAD`: [**iOS**] Prevents the Bluetooth plugin from being initialised until first access to the `ble` window object. This allows an application to warn the user before the Bluetooth access permission is requested.
 
+-   `BLUETOOTH_RESTORE_STATE`: [**iOS**] Enable Bluetooth state restoration, allowing an app to be woken up to receive scan results and peripheral notifications. This is needed for background scanning support. See [iOS restore state](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html#//apple_ref/doc/uid/TP40013257-CH7-SW13). For more information about background operation with this plugin, see [Background Scanning and Notifications on iOS](#background-scanning-and-notifications-on-ios).
+
+-   `ACCESS_BACKGROUND_LOCATION`: [**Android**] Tells the plugin to request the ACCESS_BACKGROUND_LOCATION permission on Android 10 & Android 11 in order for scanning to function when the app is not visible.
+
+## Android permission conflicts
+
 If you are having Android permissions conflicts with other plugins, try using the `slim` variant of the plugin instead with `cordova plugin add cordova-plugin-ble-central@slim`. This variant excludes all Android permissions, leaving it to the developer to ensure the right entries are added manually to the `AndroidManifest.xml` (see below for an example).
@@ -81,6 +104,2 @@
 
-If your app targets Android 10 (API level 29) or higher, you may need the ACCESS_BACKGROUND_LOCATION permission on Android 10 & Android 11 in order for scanning to function when your app is not visible. To enable this permission and feature, set `ACCESS_BACKGROUND_LOCATION ` to true when installing:
-
-    --variable ACCESS_BACKGROUND_LOCATION=true
-
 For the best understanding about which permissions are needed for which combinations of target SDK version & OS version, see [Android Bluetooth permissions](https://developer.android.com/guide/topics/connectivity/bluetooth/permissions)
@@ -90,4 +109,2 @@
 
-## Methods
-
 -   [ble.scan](#scan)
@@ -1285,3 +1302,4 @@ -   [ble.startScan](#startscan)
 
-Ideally a common format (map or array) would be returned for both platforms in future versions. If you have ideas, please contact me.
+To get consistent advertising data payloads across platforms, you can use
+the [ble-central-advertisements](https://github.com/jospete/ble-central-advertisements) module.
 
@@ -1288,0 +1306,0 @@ ## Android

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

445580

increased by0.32%

Number of lines in readme file

1479

increased by1.23%

Worsened metrics

Number of low quality alerts

2

increased by100%

No dependency changes