Ship Web Bluetooth on iOS Safari.

Quick Start

WebBLE brings the Web Bluetooth API to iOS Safari via a Safari extension and companion app. The canonical web integration is the core auto polyfill, so your existing Web Bluetooth code can stay standard.

Option 1: Core Auto Polyfill (Canonical)

npm install @ios-web-bluetooth/core

import '@ios-web-bluetooth/core/auto';

// Your existing Web Bluetooth code stays standard
const device = await navigator.bluetooth.requestDevice({
  filters: [{ services: ['heart_rate'] }]
});

On Safari iOS, the package activates the extension-backed polyfill when available. On browsers with native Web Bluetooth support, it stays out of the way.

Option 2: React SDK

npm install @ios-web-bluetooth/react

import { WebBLEProvider, useBluetooth } from '@ios-web-bluetooth/react';
import '@ios-web-bluetooth/core/auto';

function App() {
  return (
    <WebBLEProvider>
      <MyBluetoothApp />
    </WebBLEProvider>
  );
}

Option 3: Add Install Detection Later

If you need install-state UX, analytics, or a custom missing-extension flow, layer that on after the core path is working.

How It Works

The system has three parts:

1. Safari Extension — A free iOS app with a Safari Web Extension that bridges CoreBluetooth to web pages
2. Content Script — Injected by the extension, stays dormant by default, and activates the native WebBLE pipeline for the current tab when the user requests it
3. Web SDK — Provides the Safari iOS polyfill, optional install detection, and React helpers

When a user visits your site on iOS Safari:

1. Your page calls standard Web Bluetooth code
2. If the extension is active on Safari iOS, WebBLE exposes navigator.bluetooth through the extension bridge
3. If the extension is missing, you can show your own instructions or add the optional detection package

Browser Support

@ios-web-bluetooth/core/auto

The core package is the recommended integration surface for production apps that want the standard Web Bluetooth API.

Basic Usage

npm install @ios-web-bluetooth/core

import '@ios-web-bluetooth/core/auto';

const device = await navigator.bluetooth.requestDevice({
  filters: [{ services: ['battery_service'] }]
});

What It Does

• Detects whether the browser already supports Web Bluetooth
• Activates the Safari iOS extension bridge when available
• Polyfills navigator.bluetooth for standard Web Bluetooth calls
• Keeps your app code aligned with the Web Bluetooth API instead of a custom runtime API

React SDK

The @ios-web-bluetooth/react package provides React hooks and components on top of the same standard Web Bluetooth model.

npm install @ios-web-bluetooth/react

Provider Setup

Wrap your app with WebBLEProvider after loading the core polyfill:

import { WebBLEProvider } from '@ios-web-bluetooth/react';
import '@ios-web-bluetooth/core/auto';

function App() {
  return (
    <WebBLEProvider>
      <MyBluetoothApp />
    </WebBLEProvider>
  );
}

Using Hooks

import { useWebBLE, useDevice, useCharacteristic } from '@ios-web-bluetooth/react';

function HeartRateMonitor() {
  const { requestDevice, isAvailable } = useWebBLE();

  const handleConnect = async () => {
    const device = await requestDevice({
      filters: [{ services: ['heart_rate'] }],
    });
    // device is a standard BluetoothDevice
  };

  return (
    <button onClick={handleConnect} disabled={!isAvailable}>
      Connect Heart Rate Monitor
    </button>
  );
}

Available Hooks

Components

Install Detection

@ios-web-bluetooth/detect is an optional package for extension detection and missing-extension UX. Use it when your product needs install-aware messaging; skip it if the core polyfill is enough.

npm install @ios-web-bluetooth/detect

Programmatic API

import { initIOSWebBLE } from '@ios-web-bluetooth/detect';

await initIOSWebBLE({
  operatorName: 'FitTracker',
  banner: {
    mode: 'sheet',          // 'sheet' (default) or 'banner'
    dismissDays: 14,        // suppress after dismiss
  },
  onReady() { /* extension installed */ },
  onNotInstalled() { /* show fallback */ },
});

Auto-Init (Zero Code)

Import the auto module and configure via meta tags:

<meta name="ioswebble-name" content="My App">
<script type="module">
  import '@ios-web-bluetooth/core/auto';
  import '@ios-web-bluetooth/detect/auto';
</script>

React Integration

import { IOSWebBLEProvider, useIOSWebBLE } from '@ios-web-bluetooth/detect/react';

function Layout({ children }) {
  return (
    <IOSWebBLEProvider
      operatorName="FitTracker">
      {children}
    </IOSWebBLEProvider>
  );
}

Detection API

isIOSSafari()

Returns true if the current browser is Safari on iOS (including iPad).

import { isIOSSafari } from '@ios-web-bluetooth/detect';

if (isIOSSafari()) {
  // Running on iOS Safari
}

isExtensionInstalled()

Returns a Promise<boolean> that resolves after checking for the extension (waits up to 2 seconds for injection).

import { isExtensionInstalled } from '@ios-web-bluetooth/detect';

const installed = await isExtensionInstalled();

initIOSWebBLE(options)

Main entry point. Detects iOS Safari, checks extension state, and lets you hook in custom install guidance if needed.

Install UX Options

Configure how missing-extension guidance appears when you use the optional detection package.

React Hooks

useWebBLE()

Returns the core WebBLE context. Must be used inside <WebBLEProvider>.

useIOSWebBLE()

From @ios-web-bluetooth/detect/react. Returns detection state for optional install-aware UI.

Events

The SDK dispatches custom events on the window object:

// Listen for extension detection
window.addEventListener('ioswebble:ready', () => {
  console.log('Extension is active!');
});

Background Sync

Use navigator.webble.backgroundSync to keep approved BLE devices active while Safari is backgrounded and to deliver iOS notifications for important BLE events.

requestPermission()

Call this from a direct user gesture. It resolves to 'granted', 'denied', or 'prompt'.

document.querySelector('#enable-background-sync')?.addEventListener('click', async () => {
  const permission = await navigator.webble.backgroundSync.requestPermission();

  if (permission !== 'granted') {
    console.log('Background notifications not enabled:', permission);
    return;
  }

  console.log('Background notifications enabled');
});

Background Connection

requestBackgroundConnection({ deviceId }) asks the companion app to keep a granted device connected in the background. It is silent by design and does not show an iOS notification on its own.

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

await device.gatt.connect();

await navigator.webble.backgroundSync.requestBackgroundConnection({
  deviceId: device.id
});

Characteristic Notifications

registerCharacteristicNotifications(options) fires an iOS notification when a characteristic changes while Safari is backgrounded.

condition is required and is evaluated natively before iOS notification delivery.

NotificationTemplate

ReplyActionConfig

Use friendly text here for forward compatibility. The initial release uses the standard iOS inline reply UI.

const messageAlerts = await navigator.webble.backgroundSync.registerCharacteristicNotifications({
  deviceId: device.id,
  serviceUUID: '12345678-1234-1234-1234-123456789abc',
  characteristicUUID: '87654321-4321-4321-4321-cba987654321',
  condition: {
    decode: 'uint8',
    operator: 'changed',
    threshold: 0
  },
  cooldownSeconds: 15,
  template: {
    title: 'Message from {{device.name}}',
    body: '{{value.utf8}}',
    url: 'https://example.com/messages',
    sound: true
  },
  replyAction: {
    actionTitle: 'Reply',
    placeholder: 'Send a quick response'
  }
});

Beacon Scanning

registerBeaconScanning(options) matches BLE advertisements and delivers an iOS notification when a filter hits.

cooldownSeconds throttles how often iOS shows a notification. It does not control scan frequency.

BLEScanFilter

const beaconRegistration = await navigator.webble.backgroundSync.registerBeaconScanning({
  filters: [
    { services: ['feaa'] },
    {
      services: ['12345678-1234-1234-1234-123456789abc'],
      namePrefix: 'Sensor-'
    }
  ],
  cooldownSeconds: 60,
  template: {
    title: 'Nearby BLE beacon',
    body: '{{device.name}} is advertising nearby',
    url: 'https://example.com/beacons',
    sound: true
  }
});

Managing Registrations

Use getRegistrations(), unregister(id), and update(id, template) to manage registrations for the current origin.

const registrations = await navigator.webble.backgroundSync.getRegistrations();

for (const registration of registrations) {
  console.log(registration.id, registration.type);
}

await navigator.webble.backgroundSync.update(messageAlerts.id, {
  title: 'New device message',
  body: '{{value.utf8}}'
});

await navigator.webble.backgroundSync.unregister(beaconRegistration.id);

BackgroundRegistration handle

Security notes

• template.url must use https:// and is only opened when it matches the same origin as the page that registered it.
• deviceId is scoped to devices previously granted via requestDevice() for the current site flow.
• Template values are sanitized before iOS renders the notification, and only supported {{...}} placeholders are interpolated.

Complete example

const permission = await navigator.webble.backgroundSync.requestPermission();

if (permission !== 'granted') {
  throw new Error('Enable notifications to use background BLE alerts');
}

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

await device.gatt.connect();

const keepAlive = await navigator.webble.backgroundSync.requestBackgroundConnection({
  deviceId: device.id
});

const heartRateAlerts = await navigator.webble.backgroundSync.registerCharacteristicNotifications({
  deviceId: device.id,
  serviceUUID: 'heart_rate',
  characteristicUUID: 'heart_rate_measurement',
  condition: {
    decode: 'uint8',
    operator: 'gt',
    threshold: 120
  },
  cooldownSeconds: 30,
  template: {
    title: 'Heart rate update',
    body: '{{device.name}} sent {{value.hex}} at {{timestamp}}',
    url: 'https://example.com/monitor',
    sound: true
  }
});

const activeRegistrations = await navigator.webble.backgroundSync.getRegistrations();
console.log(activeRegistrations.map(({ id, type }) => ({ id, type })));

await heartRateAlerts.update({
  body: 'Latest payload from {{device.name}}: {{value.hex}}'
});

// Later, when you no longer need background delivery:
await heartRateAlerts.unregister();

Troubleshooting

Extension not detected after installation

The user may have enabled the extension but not granted website permissions. They need to:

1. In Safari, tap aA in the address bar
2. Tap the WebBLE icon (may have a warning badge)
3. Choose "Always Allow"
4. Then "Always Allow on Every Website"

Extension works on some sites but not others

The user may have chosen per-site permissions. They need to grant "Always Allow on Every Website" for consistent behavior.

HTTPS required

Web Bluetooth requires a secure context. Ensure your site uses HTTPS (or localhost for development).

navigator.bluetooth is undefined

• On iOS Safari: the extension is not installed or not granted permissions
• On Firefox: Web Bluetooth is not supported
• On Chrome/Edge: should work natively — check chrome://flags/#enable-experimental-web-platform-features

Privacy

WebBLE is designed with privacy as a core principle:

• All BLE data processed locally. Bluetooth communication happens entirely on-device between the browser and CoreBluetooth. No data is ever proxied through a server.
• No BLE data leaves the device. Bluetooth communication stays on-device between Safari, the extension, and CoreBluetooth. WebBLE does not proxy device traffic through a server.
• No browsing history is stored or transmitted for BLE functionality. The extension uses Safari page integration to expose the API, but WebBLE does not inspect, retain, or transmit page content or browsing history to deliver Bluetooth connectivity.
• Optional analytics stay minimal. When a developer explicitly enables SDK analytics, the service records limited install-state events such as hostname, user agent, timestamp, and the integration identifier tied to that developer account.
• Proprietary product, public docs. WebBLE publishes detailed setup and API documentation, but the product should be evaluated as proprietary software today.