# Cordova BLE vs. WebBLE

If you are trying to ship Bluetooth Low Energy on iPhone today, the historical answer is one of a handful of Cordova plugins built around native CoreBluetooth. WebBLE is a different architecture. This page is an honest comparison for teams weighing the two.

## TL;DR

- **Cordova** wraps a native app around a web view and exposes plugins to JavaScript. You ship to the App Store as a native app.
- **WebBLE** is a Safari Web Extension that polyfills the standard W3C `navigator.bluetooth` on the *regular* Safari. Your app stays a web page; only the extension is distributed through the App Store — once, and the user installs it.

If you want "a web page that works on iPhone," WebBLE. If you want "a full native-feeling iOS app that happens to be HTML," Cordova.

## Comparison

| Axis | Cordova + BLE plugin | WebBLE |
|------|----------------------|--------|
| **API surface** | Plugin-specific (`ble.startScan`, `ble.connect`, …) | Standard W3C `navigator.bluetooth` |
| **Portability** | iOS-only plugin code; distinct plugins per platform | Works on Chrome/Edge unchanged; iOS via polyfill |
| **Distribution** | App Store submission every release | Web deploy (Cloudflare Pages, Vercel, …); extension updates independently |
| **App Store distribution** | Per-release submission required | One-time user install of the WebBLE extension |
| **PWA compatibility** | No — you shipped a native app, not a PWA | Yes — a normal PWA gets BLE the moment the extension is enabled |
| **Code reuse with web** | Shared view code; BLE code must fork | 100 % reuse — same `navigator.bluetooth` as Chrome |
| **Background BLE** | Native background modes possible; plugin-dependent | Premium `window.webbleIOS.backgroundSync` via companion app |
| **Bundle size on device** | Entire web-view app + plugins | None — only the WebBLE extension, installed once |
| **Update cadence** | Blocked by App Review | Deploy to the web instantly |
| **Platform coverage** | iOS + Android (if plugin supports) | Any browser where the user has WebBLE; Chrome/Edge/Opera elsewhere |
| **Enterprise distribution** | MDM / TestFlight / private App Store | Open web URL |
| **Licensing cost** | Typically MIT plugins + Apple Developer Program | Polyfill free; iOS premium via companion app |

## When Cordova is the right answer

- You are already shipping a Cordova/Capacitor/Ionic app and BLE is a small addition.
- You need OS integration that exceeds any web API (HealthKit deep hooks, CarPlay, etc.).
- Your users acquire your product through the App Store and would reject a web-only flow.

## When WebBLE is the right answer

- Your product is already — or should be — a web page.
- You want one codebase that runs on Chrome desktop and iOS Safari without platform forks.
- You need to ship fixes the same day, without Apple review cycles.
- You want a PWA story without losing BLE on iOS.
- You are already using `navigator.bluetooth` on Chrome and want iOS parity without porting.

## Migration path

Porting a Cordova BLE app to WebBLE usually means deleting the plugin calls and replacing them with the standard API:

```js
// Cordova (plugin-specific)
ble.startScan([], (device) => { ... });

// WebBLE (standard)
const device = await navigator.bluetooth.requestDevice({
  filters: [{ services: ['heart_rate'] }]
});
```

The W3C API lacks some free-scan affordances — iOS enforces a system chooser UI for `requestDevice` — but otherwise the mapping is direct. See the [quickstart](../quickstart.md) and [API reference](../api-reference.md).