接入文档

WebBT 设备桥接 SDK v1 接入文档:检测桥接对象、连接广播与 GATT 设备、发送控制帧并处理错误码。

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 内置版本同源维护。