WebBT设备接入指南
SDK v1 · 适用于 WebBT 1.0 及以上版本
WebBT在所有 http(s) 主框架页面注入 window.__webbtDevice。网站不需要申请或登记,也不需要在 App 内配置域名。用户可以在设置中关闭「网站蓝牙访问」;关闭后所有设备调用返回 permission_denied。
1. 检测桥
if (typeof window.__webbtDevice === 'object') {
console.log('WebBT bridge', window.__webbtDevice.version);
} else {
console.log('当前环境没有WebBT桥');
}
桥只注入主框架。iframe、file://、data:、blob: 页面没有桥。页面不需要、也无法读取会话 nonce。文中的 https://shop.example 仅作占位示例。
2. 快速开始
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 一览
| 方法 | 返回 | 作用 |
|---|---|---|
probe() |
{ok:true, version:1} |
检测桥是否存活 |
status() |
BridgeStatus 或 {ok:false,error} |
读取当前设备状态 |
connect(device) |
{ok:true} / {ok:false,error} |
连接设备,当前标签成为 owner |
frame(hex) |
{ok:true} / {ok:false,error} |
发送一帧十六进制数据 |
stop() |
{ok:true} / {ok:false,error} |
发送停止帧,不断开 |
disconnect() |
{ok:true} / {ok:false,error} |
停止并断开 |
onStatus(cb) |
取消订阅函数 | 订阅状态推送 |
所有方法都返回 Promise。status() 成功时直接返回状态对象,不包 {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 标识解析顺序:mac → modelInfo.deviceId → id。三者都没有时返回 bad_device。逻辑设备 id 是 deviceCode ?? deviceId,用于重复连接同一设备的幂等判断。
- 广播设备:
modelInfo.connectionType = 1。App 使用 BLE 广播承载命令,不建立 GATT 链路。 - GATT 设备:
modelInfo.connectionType = 0。App 按标识连接;isAuth = 1时执行 CRC8 鉴权。 - iOS 没有 MAC:把 CoreBluetooth identifier 放进
modelInfo.deviceId或id。 - Android 若只有型号名:可省略
mac,App 会用modelInfo.modelName扫描附近广播获取 MAC。
5. 示例:广播设备
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. 示例:GATT 设备
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. 用户授权与总开关
- 「网站蓝牙访问」默认开启,对所有网站生效,不需要逐站点配置。
- 首次有站点调用
connect时,App 展示一次性、非阻塞告知;用户仍然可以继续连接。 - 用户关闭总开关后:
connect返回permission_denied;- 已连接设备会被安全停机并断开;
- 设备停机并断开后,owner 标记会被清除;此后的
frame返回permission_denied,stop/disconnect返回not_owner。
- 页面应处理
permission_denied,提示用户到设置中开启,而不是反复重试。
8. 错误码
| 错误码 | 含义 |
|---|---|
nonce |
调用不能证明来自当前文档 |
origin |
当前文档不是 http(s),或信封 origin 与真实文档不一致 |
bad_request |
参数不是 {nonce, origin, method, args} |
bad_device |
connect 缺少 device、name 或可用标识 |
connect_failed |
权限、协议、超时、鉴权或特征值失败 |
bluetooth_off |
蓝牙未开启或不可用 |
unsupported_device |
设备类型不受支持 |
invalid_ble_id |
设备标识既无可用 MAC,也无法按名称扫描 |
device_not_found |
按名称扫描未找到设备 |
scan_permission_denied |
未授予蓝牙扫描权限 |
broadcast_unsupported |
当前设备不支持 BLE 广播 |
broadcast_permission_denied |
未授予蓝牙广播权限 |
connection_exception |
底层连接异常(附原始信息) |
stop_failed |
停止帧发送失败 |
permission_denied |
用户关闭了网站蓝牙访问 |
device_busy |
另一个标签页正在使用设备 |
not_owner |
当前标签不是设备 owner |
empty_hex |
frame 的 hex 为空 |
frame_failed |
hex 非法、未连接或底层写入失败 |
unknown_method |
方法名不在 v1 |
exception |
设备层异常 |
disposed |
WebView 会话已销毁 |
status() 不会返回错误码;未连接时返回 {state:'disconnected'}。
9. 生命周期与安全规则
- 同一时刻只允许一个标签页拥有设备。
- 非 owner 调用
connect返回device_busy;调用frame/stop/disconnect返回not_owner。 - 非 owner 的
status()只得到{state:'connected', busy:true},不会泄露设备名。 - owner 标签关闭、导航或刷新时,App 先
stop再disconnect。 - owner 在后台不会自动释放;只有关闭标签、导航、关闭总开关或手动断开才释放。
- 设备意外断开时,App 清除 owner 并向所有页面推送
disconnected。 - 页面应在
beforeunload或路由离开前主动stop();进程被系统强杀时 App 没有执行机会。
10. 状态对象
interface BridgeStatus {
state: 'disconnected' | 'connecting' | 'authenticating'
| 'connected' | 'disconnecting';
deviceId?: string;
deviceName?: string;
transport?: 'broadcast' | 'gatt';
error?: string;
}
11. 常见问题
找不到 window.__webbtDevice
确认页面由WebBT打开,且位于主框架;iframe 内没有桥。
connect_failed
检查蓝牙是否开启、权限是否授予、modelInfo 是否足以选择协议、GATT 标识是否正确。可调用 status() 读取 error 详情。
Android 连接失败但标识看起来正确
后端下发的可能是型号模板 UUID,不是 MAC。补充 modelInfo.modelName,让 App 按型号名扫描。
device_busy
另一个标签页已经是 owner。先在该标签页 disconnect(),或关闭该标签页。
not_owner
当前页面不是 owner;不要尝试抢占设备。
12. 版本兼容
probe()返回的version为1。- v1 不提供 GATT 原始通知流、电池查询、OTA、重连策略或自动档位发帧。
- 协议升级会保留现有方法;新增能力通过新方法或版本号区分。
- 接入文档与 App 内置版本同源维护。