WebBLE SDK Integration

What this does

WebBLE is a Web Bluetooth SDK for web apps. It works on Chrome natively and on iOS Safari via a companion app + Safari extension. The SDK provides scan, connect, read/write/subscribe operations for BLE devices.

Package Routing Table

Scope: All packages are published under @ios-web-bluetooth/*.

Integration Path A: New BLE Application

Step 1: Install

npm install @ios-web-bluetooth/core

Step 2: Scan and connect

import { WebBLE } from '@ios-web-bluetooth/core'

const ble = new WebBLE()
const device = await ble.requestDevice({
  filters: [{ services: ['heart_rate'] }]
})
await device.connect()

Step 3: Read or subscribe

const value = await device.read('heart_rate', 'heart_rate_measurement')

device.subscribe('heart_rate', 'heart_rate_measurement', (data) => {
  console.log('Heart rate:', data)
})

Step 4 (optional): Use a typed profile

npm install @ios-web-bluetooth/profiles

import { HeartRateProfile } from '@ios-web-bluetooth/profiles'

const profile = new HeartRateProfile(device)
profile.onHeartRate((data) => {
  console.log(`BPM: ${data.heartRate}, Contact: ${data.contactDetected}`)
})

Step 5 (optional): Add iOS Safari support

npm install @ios-web-bluetooth/detect

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

Integration Path B: Existing Web Bluetooth App (iOS Safari support)

Step 1: Install

npm install @ios-web-bluetooth/detect

Step 2: Add detection

For React/Next.js:

import { IOSWebBLEProvider } from '@ios-web-bluetooth/detect/react'
// Wrap your app:
<IOSWebBLEProvider>{children}</IOSWebBLEProvider>

For any framework:

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

For plain HTML:

<script src="https://ioswebble.com/webble.js"></script>

Step 3: Verify

npx ioswebble check

MCP Server (for agent tools)

{
  "ioswebble": {
    "command": "npx",
    "args": ["-y", "@ios-web-bluetooth/mcp"]
  }
}

Rules

• Do NOT modify existing navigator.bluetooth calls — the extension handles compatibility
• Use human-readable UUID names ('heart_rate') not hex ('0x180D') — the SDK resolves automatically
• Use @ios-web-bluetooth/profiles for standard devices instead of writing raw GATT parsing code
• For React, use @ios-web-bluetooth/react hooks instead of raw event listeners
• API key is optional (campaign tracking only)
• The detect snippet only shows an install banner on iOS Safari when the extension is not installed
• Works alongside native Web Bluetooth on Chrome/Android (no-op on non-iOS)
• Requires HTTPS (localhost excepted)