WebBT Device Integration Guide
SDK v1 · for WebBT 1.0 and later
WebBT injects window.__webbtDevice into every http(s) main frame. No registration or domain configuration is required. Users can turn off Website Bluetooth access in Settings; when it is off, every device call returns permission_denied.
1. Detect the bridge
if (typeof window.__webbtDevice === 'object') {
console.log('WebBT bridge', window.__webbtDevice.version);
} else {
console.log('No WebBT bridge in this document');
}
The bridge is injected into the main frame only. Iframes, file://, data: and blob: documents do not receive it. Pages cannot read the session nonce. https://shop.example is a placeholder example.
2. Quick start
const sdk = window.__webbtDevice;
if (!sdk) throw new Error('WebBT bridge unavailable');
const probe = await sdk.probe();
console.log('bridge version', probe.version);
const off = sdk.onStatus((status) => {
console.log('device status', status);
});
const result = await sdk.connect({
name: 'Demo Light',
id: 'demo-1',
deviceCode: 'demo-1',
modelInfo: {
id: 'demo-model',
modelName: 'Demo Light',
connectionType: 1,
isPrivate: 1,
},
});
if (result.ok) {
await sdk.frame('AB0105050505050505050505');
await sdk.stop();
await sdk.disconnect();
}
off();
3. API
| Method | Result | Purpose |
|---|---|---|
probe() |
{ok:true, version:1} |
Check that the bridge is alive |
status() |
BridgeStatus or {ok:false,error} |
Read current device status |
connect(device) |
{ok:true} / {ok:false,error} |
Connect; this tab becomes owner |
frame(hex) |
{ok:true} / {ok:false,error} |
Send one hex frame |
stop() |
{ok:true} / {ok:false,error} |
Send the stop frame without disconnecting |
disconnect() |
{ok:true} / {ok:false,error} |
Stop and disconnect |
onStatus(cb) |
unsubscribe function | Subscribe to status pushes |
Every method returns a Promise. status() resolves directly to the status object on success, not to {ok:true, ...}.
4. DevicePayload
interface BridgeDevicePayload {
name: string;
mac?: string;
id?: string;
deviceCode?: string;
pic?: string;
modelInfo?: {
id?: string;
modelName?: string;
deviceId?: string;
connectionType?: 0 | 1;
isPrivate?: 0 | 1;
isAuth?: 0 | 1;
serviceUUID?: string;
writeUUID?: string;
readUUID?: string;
};
functions?: BridgeFunction[];
modes?: BridgeMode[];
}
BLE identity resolution order: mac → modelInfo.deviceId → id. If all are empty, connect returns bad_device. The logical device id is deviceCode ?? deviceId and is used for idempotent reconnects.
- Broadcast device:
modelInfo.connectionType = 1. Commands travel over BLE advertising; no GATT link is created. - GATT device:
modelInfo.connectionType = 0. The app connects by identity. WhenisAuth = 1, it performs the CRC8 handshake. - iOS has no MAC: put the CoreBluetooth identifier in
modelInfo.deviceIdorid. - If Android only has a model name, omit
macand providemodelInfo.modelName; the app scans nearby advertisements to recover the MAC.
5. Example: broadcast device
await sdk.connect({
name: 'Demo Broadcast',
id: 'demo-broadcast-1',
deviceCode: 'demo-broadcast-1',
modelInfo: {
id: 'demo-broadcast-model',
modelName: 'Demo Broadcast',
connectionType: 1,
isPrivate: 1,
},
});
6. Example: GATT device
await sdk.connect({
name: 'Demo GATT',
mac: 'AA:BB:CC:DD:EE:FF',
id: 'demo-gatt-1',
modelInfo: {
id: 'demo-gatt-model',
modelName: 'Demo GATT',
connectionType: 0,
isPrivate: 1,
isAuth: 1,
serviceUUID: '0000ff00-0000-1000-8000-00805f9b34fb',
writeUUID: '0000ff02-0000-1000-8000-00805f9b34fb',
readUUID: '0000ff01-0000-1000-8000-00805f9b34fb',
},
});
7. User consent and the global switch
- Website Bluetooth access is on by default and applies to every site. There is no per-site configuration.
- The first
connectfrom a site shows a one-time, non-blocking notice. The connection still proceeds. - When the user turns the switch off:
connectreturnspermission_denied;- any connected device is safely stopped and disconnected;
- after the device is stopped and disconnected the owner mark is cleared;
subsequent
framecalls returnpermission_denied, andstop/disconnectreturnnot_owner.
- Handle
permission_deniedby asking the user to enable the setting; do not retry in a loop.
8. Error codes
| Code | Meaning |
|---|---|
nonce |
The call cannot be proven to come from the current document |
origin |
The document is not http(s), or the envelope origin does not match |
bad_request |
Arguments are not {nonce, origin, method, args} |
bad_device |
connect lacks a device, name or usable identity |
connect_failed |
Permission, protocol, timeout, authentication or GATT failure |
bluetooth_off |
Bluetooth is off or unavailable |
unsupported_device |
The device type is not supported |
invalid_ble_id |
The identifier has no usable MAC and no name to scan for |
device_not_found |
The name scan found no matching device |
scan_permission_denied |
Bluetooth scan permission was not granted |
broadcast_unsupported |
This device does not support BLE advertising |
broadcast_permission_denied |
Bluetooth advertising permission was not granted |
connection_exception |
Low-level connection exception (raw message attached) |
stop_failed |
The stop frame could not be sent |
permission_denied |
Website Bluetooth access is off |
device_busy |
Another tab currently owns the device |
not_owner |
This tab is not the device owner |
empty_hex |
frame received an empty hex string |
frame_failed |
Invalid hex, not connected, or transport write failure |
unknown_method |
Method is not part of v1 |
exception |
Unhandled device-layer exception |
disposed |
The WebView session has been disposed |
status() does not return an error code; when disconnected it returns {state:'disconnected'}.
9. Lifecycle and safety rules
- Only one tab can own the device at a time.
- A non-owner
connectreturnsdevice_busy;frame/stop/disconnectreturnnot_owner. - A non-owner
status()only receives{state:'connected', busy:true}; device details are hidden. - When the owner tab closes, navigates or reloads, the app calls
stopand thendisconnect. - An owner tab in the background keeps the connection. It is released only on close, navigation, switching the global setting off, or manual disconnect.
- On an unexpected device disconnect the app clears the owner and pushes
disconnectedto every page. - Call
stop()before leaving the page. If the process is killed, the app has no chance to run cleanup.
10. Status object
interface BridgeStatus {
state: 'disconnected' | 'connecting' | 'authenticating'
| 'connected' | 'disconnecting';
deviceId?: string;
deviceName?: string;
transport?: 'broadcast' | 'gatt';
error?: string;
}
11. Troubleshooting
window.__webbtDevice is undefined
Open the page in WebBT and make sure it is the main frame. Iframes do not receive the bridge.
connect_failed
Check that Bluetooth is on, permissions are granted, modelInfo is sufficient to pick a protocol, and the GATT identity is correct. Call status() to read the error field.
Android fails even though the identity looks valid
The server may be sending a model-template UUID instead of a MAC. Add modelInfo.modelName so the app can scan by model name.
device_busy
Another tab owns the device. Disconnect there first, or close that tab.
not_owner
This page is not the owner. Do not try to take over the device.
12. Version compatibility
probe()returnsversion: 1.- v1 does not expose raw GATT notifications, battery queries, OTA, reconnect policy or automatic intensity commands.
- Protocol upgrades keep existing methods; new capabilities arrive through new methods or a version bump.
- This guide is shipped inside the app and updated with the protocol.