Bluetooth Connectivity
Bluetooth is a short-range wireless technology that lets devices communicate and share data using radio waves — no cables, no router, no internet connection needed. It works at distances of up to roughly 10 metres (30 feet).
The WebToNative Bluetooth add-on brings this capability into your app. From your website's JavaScript, you can scan for nearby devices, initiate pairing, and disconnect — giving users a seamless, integrated experience with the Bluetooth accessories they already use.
This add-on is available for Android only. It’s included free with the Business plan, and you can start with the Pro plan to access this add-on on WebToNative.
Where to Find It In Your Dashboard
My Apps ➡️ Edit your app ➡️ Add-ons ➡️ +ADD ➡️Device and Hardware ➡️ Bluetooth Connectivity ➡️ Activate
Compatible device types
Bluetooth speakers
Headsets & earbuds
Printers
Smart devices
Wearables
Other BT accessories
Bluetooth Functionalities
| How It Works |
|---|
| The app checks whether Bluetooth is enabled on the user's device before scanning. |
| The app scans for nearby Bluetooth devices and returns a list of everything it finds within range. |
| The list of available devices is displayed inside your app — the user sees device names and can choose one to connect to. |
| The app pairs with the selected device using its Bluetooth address, with a timeout so it doesn't hang indefinitely if the device doesn't respond. |
| When done, the app can disconnect from the device — and receives a callback confirming the unpair result. |
JavaScript API functions
Import the WebToNative JavaScript file first, then call these functions from your website to control Bluetooth from within the app.
Check Bluetooth status
Before scanning, check whether Bluetooth permission is currently granted on the user's device. If it isn't, this triggers the OS permission prompt; if the user has permanently denied it, you'll get a distinct status so you can guide them to Settings. This is handled through the Permissions Handling API.
When to use
Status - ALLOWED, NOT_ALLOWED, PERMANENTLY_BLOCKED
Returns (in callback)
Always call this first. Scanning will fail silently if permission isn't granted — checking upfront lets you show a helpful prompt instead. On PERMANENTLY_BLOCKED, direct the user to the app's system settings.
Read the Document for complete function guide: https://docs.webtonative.com/javascript-apis/permissions-handling (opens in a new tab)
Bluetooth.startBluetoothScan()
Starts scanning for Bluetooth devices within range of the user's phone. The scan runs for about 14 seconds before the callback fires with a list of all nearby Bluetooth devices — connected, already-paired, and newly discovered — which you can display to the user for selection.
| Parameters | Description |
|---|---|
| callback | Function called when the scan completes |
| Returns (in callback) | Description |
|---|---|
| data | Array of nearby Bluetooth devices found during the scan |
| Each device object | Description |
|---|---|
| mac_address | Bluetooth hardware address — use this to pair/unpair |
| name | Device name, or "Unknown Device" if unavailable |
| connected | Whether the device is currently connected |
| paired | Whether the device is already paired/bonded |
| discovered | Whether the device was newly found during this scan's discovery pass |
| device_class | Android Bluetooth device class identifier |
| rssi | Signal strength indicator |
Bluetooth.pairDevice()
Connects to a specific Bluetooth device using its unique hardware address. You pass a timeout value — the number of milliseconds the app should attempt to connect before giving up. The callback tells you whether the device was successfully paired or not.
| Parameters | Description |
|---|---|
| address | The Bluetooth hardware address of the target device (from the scan results) |
| timeout | Time in seconds to attempt connection before returning a failure. Defaults to 30 if omitted. |
| callback | Function called with the pairing result |
| Returns (in callback) | Description |
|---|---|
| result | PAIRED, NOT_PAIRED, ERROR_DURING_PAIRING |
Bluetooth.unpairDevice()
Disconnects from a currently paired Bluetooth device using its address. The callback returns whether the unpair was successful or if an error occurred during the process.
| Parameters | Description |
|---|---|
| address | The Bluetooth hardware address of the device to disconnect |
| callback | Function called with the unpair result |
| Returns (in callback) | Description |
|---|---|
| result | UNPAIRED, ERROR_DURING_UNPAIRING |
Full code examples (Plain JS and npm) for all Bluetooth functions are in the developer documentation. https://docs.webtonative.com/javascript-apis/bluetooth-android (opens in a new tab)
Frequently Asked Questions
Where do I get the device address to pair or unpair?
The device address is returned by startBluetoothScan() — each entry in the scan results includes a mac_address field alongside the device name. Store that address from the scan result and pass it to pairDevice() or unpairDevice().
What should I set as the timeout for pairDevice()?
The timeout is in seconds, not milliseconds — how long the app waits before giving up on the connection attempt. It defaults to 30 if you omit it. A value of 10 is a reasonable default for most devices; don't pass a large number like 10000 expecting milliseconds — that would make the app wait over 2 hours. If the connection isn't established within the timeout period, the callback fires with a NOT_PAIRED result so you can show the user an appropriate message.
What happens if Bluetooth is off on the user's device?
The scan will not return any devices and pairing will not work. Always check Bluetooth status first using the Permissions Handling API before calling startBluetoothScan(). If Bluetooth is off, show the user a prompt explaining that they need to enable Bluetooth in their device settings to use this feature.
Is Bluetooth Connectivity available on iOS?
No — Bluetooth Connectivity is currently Android only. iOS restricts third-party Bluetooth access to specific MFi-certified hardware and frameworks. There is no iOS equivalent available in WebToNative at this time.