Puppeteer 详解 BluetoothManufacturerDataWeb Bluetooth 模拟中的厂商数据接口【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer本篇围绕 Puppeteer API 文档中的BluetoothManufacturerData接口展开讲解这一模拟蓝牙外设厂商数据类型的两个核心字段key与data的含义、取值来源以及它如何被组合进PreconnectedPeripheral经由page.bluetooth.simulatePreconnectedPeripheral()下发到 ChromeCDP或 BiDi 会话最终驱动navigator.bluetooth.requestDevice()设备选择提示框。读完本文你将能够独立构造合法的蓝牙外设模拟配置并理解其底层 CDP/BiDi 指令链路与浏览器上下文级别的状态限制。接口定位BluetoothManufacturerData 是什么BluetoothManufacturerData是一个用于模拟模拟出的蓝牙外设peripheral厂商数据的 TypeScript 接口。官方定义如下见 BluetoothEmulation.ts 源码/** * public * Represents the simulated bluetooth peripherals manufacturer data. */ export interface BluetoothManufacturerData { /** * The company identifier, as defined by the * {link https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/|Bluetooth SIG}. */ key: number; /** * The manufacturer-specific data as a base64-encoded string. */ data: string; }在真实的 BLE低功耗蓝牙广播数据中厂商特定数据Manufacturer Specific Data由两部分组成一个 2 字节的公司标识符Company Identifier以及紧随其后的厂商自定义负载。Puppeteer 的该接口正是按这一结构建模key对应公司标识符data对应厂商自定义负载。整个接口属于BluetoothEmulation能力族emulateAdapter/simulatePreconnectedPeripheral/disableEmulation并在源码注释中标记为public且experimental实验性 API。属性详解key 与 data对应官方文档 puppeteer.bluetoothmanufacturerdata.md 中的属性表完整继承其字段定义如下属性修饰符类型说明默认值datastring厂商特定数据以 base64 编码的字符串表示keynumber公司标识符按 Bluetooth SIG 的 Assigned NumbersCompany Identifiers注册表定义keyBluetooth SIG 公司标识符key必须取 Bluetooth SIG 官方Assigned Numbers — Company Identifiers注册表中的编号例如注册表中 0x004C/76 对应 Apple、0x0005/5 对应 Intel 等公开条目完整清单以注册表为准。它是number类型即十进制整数测试用例 bluetooth-emulation.test.ts 中使用的示例值为17。在 Web Bluetooth 语义下页面代码可以通过device.gatt或广播数据过滤匹配该标识来识别特定厂商的外设因此模拟时填写正确的key对行为保真很重要。database64 编码的厂商负载data是厂商自定义负载的 base64 编码字符串而非原始字节或十六进制串。这一点在写测试或模拟配置时容易踩坑需要先把二进制负载编码为 base64 再传入。以仓库测试与官方文档示例中反复出现的AP8BAX8为例其 base64 解码后恰好是 5 个字节AP8BAX8 - 0x00 0xFF 0x01 0x01 0x5F这是一个典型的小型厂商数据负载末尾0x5F对应 ASCII 字符 Some Name 片段中常见的演示数据。这提示读者data字段的长度与内容完全由被测 Web 应用对该厂商数据的解析逻辑决定模拟时应以页面期望的字节序列为准base64 只是传输编码形式。使用位置作为 PreconnectedPeripheral 的组成部分BluetoothManufacturerData并不是直接暴露给page的而是作为PreconnectedPeripheral待模拟的蓝牙外设的一个字段数组存在。完整的周边设备类型定义见 BluetoothEmulation.ts/** * public * A bluetooth peripheral to be simulated. */ export interface PreconnectedPeripheral { address: string; name: string; manufacturerData: BluetoothManufacturerData[]; knownServiceUuids: string[]; }各字段的语义可参照 PreconnectedPeripheral 接口文档字段类型说明addressstring模拟外设的蓝牙地址示例为09:09:09:09:09:09namestring设备名称示例为SOME_NAMEmanufacturerDataBluetoothManufacturerData[]一个或多个厂商数据条目即本文主角接口knownServiceUuidsstring[]该外设已知的 GATT 服务 UUID 列表其中manufacturerData是数组类型意味着同一台模拟外设可以携带多条不同公司标识key的厂商数据逐条独立编码data。完整实战流程从 emulateAdapter 到 disableEmulation官方 BluetoothEmulation 文档 与 BluetoothEmulation.ts 源码注释中给出了同一套端到端示例完整保留如下// 1. 先把模拟的蓝牙适配器置为开机状态模拟的前提 await page.bluetooth.emulateAdapter(powered-on); // 2. 注入一台已预连接的模拟外设携带厂商数据 await page.bluetooth.simulatePreconnectedPeripheral({ address: 09:09:09:09:09:09, name: SOME_NAME, manufacturerData: [ { key: 17, data: AP8BAX8, }, ], knownServiceUuids: [12345678-1234-5678-9abc-def123456789], }); // 3. 用完后关闭模拟恢复真实行为 await page.bluetooth.disableEmulation();关键说明emulateAdapter(state, leSupported?)是模拟的前置条件Required for bluetooth simulations对应 Web Bluetooth 规范的bluetooth.simulateAdapter命令。state的合法取值由AdapterState类型约束源码定义export type AdapterState absent | powered-off | powered-on;第二参数leSupported标记适配器是否支持低功耗蓝牙两个实现中默认值均为true。simulatePreconnectedPeripheral()对应规范中的bluetooth.simulatePreconnectedPeripheral见方法文档把上表四字段的外设预连接进模拟环境。disableEmulation()对应bluetooth.disableSimulation用于清理模拟状态。这三个方法均挂载在Page实例上从 Page.ts 源码结构看Page通过抽象访问器abstract get bluetooth(): BluetoothEmulation暴露该能力CDP 与 BiDi 两套后端各自提供实现。底层实现CDP 与 BiDi 双后端的指令链路Puppeteer 对BluetoothManufacturerData的消费并不在 JS 层做校验或转换而是整体透传给浏览器协议。两个后端的实现可以对照阅读CDP 后端Chromium DevTools ProtocolCdpBluetoothEmulation 通过Connection.send发送 CDP 命令。值得注意的是emulateAdapter的实现细节async emulateAdapter(state: AdapterState, leSupported true): Promisevoid { // Bluetooth spec requires overriding the existing adapter (step 6). From the CDP // perspective, it means disabling the emulation first. await this.#connection.send(BluetoothEmulation.disable); await this.#connection.send(BluetoothEmulation.enable, { state, leSupported, }); }源码注释指出Web Bluetooth 规范bluetooth.simulateAdapter命令的第 6 步要求覆盖已存在的模拟适配器因此在 CDP 侧必须先发BluetoothEmulation.disable再发BluetoothEmulation.enable。而simulatePreconnectedPeripheral则是把整个preconnectedPeripheral对象含manufacturerData数组原样作为BluetoothEmulation.simulatePreconnectedPeripheral命令的参数发送——key与data保持 JS 侧的类型不做任何变换。BiDi 后端WebDriver BiDiBidiBluetoothEmulation 发送的是 BiDi 域命令且显式携带context浏览器上下文标识await this.#session.send(bluetooth.simulatePreconnectedPeripheral, { context: this.#contextId, address: preconnectedPeripheral.address, name: preconnectedPeripheral.name, manufacturerData: preconnectedPeripheral.manufacturerData, knownServiceUuids: preconnectedPeripheral.knownServiceUuids, });从源码结构看两个后端对manufacturerData都是零加工透传协议层面的 base64 编码与key取值合法性校验由浏览器端负责。这提示使用者如果data不是合法 base64 或字段结构不完整错误会在协议层/浏览器侧暴露而不是在 Puppeteer 侧提前拦截。测试佐证厂商数据如何驱动真实设备选择提示仓库内置的 bluetooth-emulation.test.ts 提供了该接口在真实浏览器中的完整验证链路其模拟外设配置与官方示例完全一致const SIMULATED_PERIPHERAL { address: 09:09:09:09:09:09, name: DEVICE_NAME, // SOME_NAME manufacturerData: [ { key: 17, data: AP8BAX8, }, ], knownServiceUuids: [12345678-1234-5678-9abc-def123456789], };测试的关键要点启动参数通过setupSeparateTestBrowserHooks传入--enable-featuresWebBluetoothNewPermissionsBackend与--enable-featuresWebBluetooth并设置acceptInsecureCerts: true在 HTTPS 测试服务器页面上执行Web Bluetooth 要求安全上下文。触发页面 API在页面内调用navigator.bluetooth.requestDevice({ acceptAllDevices: true, optionalServices: [] })浏览器弹出设备选择提示框。Puppeteer 侧接管page.waitForDevicePrompt()等待提示框然后可以cancel()此时页面侧的requestDevice应 reject或select(devicePrompt.devices[0])选中模拟设备此时页面拿到device.name SOME_NAME。这说明携带manufacturerData的模拟外设会真实出现在 Web Bluetooth 的设备选择列表中key/data构成了页面端过滤与识别依据。作用域与注意事项实验性 APIBluetoothManufacturerData及其所属的BluetoothEmulation三个方法在源码中均标注experimental接口签名可能随版本演进变化用于生产自动化前建议锁定版本并关注变更日志。模拟状态绑定在浏览器上下文而非页面官方文档BluetoothEmulation Remarks明确说明——Web Bluetooth 规范要求模拟适配器按顶层可导航单元top-level navigable隔离但 Chromium 当前的实现把蓝牙模拟绑定到**浏览器上下文browser context**上。因此同一浏览器上下文内的不同页面暴露出的蓝牙模拟状态会相互干扰。从源码结构看BiDi 实现按contextId发送命令CDP 实现则直接走浏览器级Connection两种路径都体现了这一上下文级作用域。若需要相互独立的模拟状态建议使用独立的浏览器上下文。执行顺序先emulateAdapter(powered-on)再simulatePreconnectedPeripheral最后disableEmulation清理跳过适配器模拟直接注入外设的行为未受支持。相关文件索引内容路径本接口官方 API 文档docs/api/puppeteer.bluetoothmanufacturerdata.md接口类型定义BluetoothManufacturerData/PreconnectedPeripheral/BluetoothEmulationpackages/puppeteer-core/src/api/BluetoothEmulation.tsCDP 后端实现packages/puppeteer-core/src/cdp/BluetoothEmulation.tsBiDi 后端实现packages/puppeteer-core/src/bidi/BluetoothEmulation.ts端到端测试用例test/src/bluetooth-emulation.test.ts外设接口文档docs/api/puppeteer.preconnectedperipheral.mdBluetoothEmulation 能力文档含完整示例docs/api/puppeteer.bluetoothemulation.md小结BluetoothManufacturerData虽只是一个双字段接口key: numberdata: string却是 Puppeteer 蓝牙模拟中承载厂商身份的关键载体key对齐 Bluetooth SIG 公司标识符注册表data以 base64 承载厂商自定义字节。它与address、name、knownServiceUuids共同构成PreconnectedPeripheral经 CDP 的BluetoothEmulation.simulatePreconnectedPeripheral或 BiDi 的bluetooth.simulatePreconnectedPeripheral命令透传给浏览器使无硬件环境的自动化测试也能完整演练requestDevice()的设备选择、取消与选中流程。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考