Integration

WebBT device bridge SDK v1: detect the bridge, connect broadcast and GATT devices, send control frames and handle error codes.

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. When isAuth = 1, it performs the CRC8 handshake.
  • iOS has no MAC: put the CoreBluetooth identifier in modelInfo.deviceId or id.
  • If Android only has a model name, omit mac and provide modelInfo.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',
  },
});
  • Website Bluetooth access is on by default and applies to every site. There is no per-site configuration.
  • The first connect from a site shows a one-time, non-blocking notice. The connection still proceeds.
  • When the user turns the switch off:
    • connect returns permission_denied;
    • any connected device is safely stopped and disconnected;
    • after the device is stopped and disconnected the owner mark is cleared; subsequent frame calls return permission_denied, and stop / disconnect return not_owner.
  • Handle permission_denied by 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 connect returns device_busy; frame / stop / disconnect return not_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 stop and then disconnect.
  • 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 disconnected to 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() returns version: 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.