支付宝小程序API 蓝牙

蓝牙 API 概览

• 错误码信息及解决方案，请参见下文 蓝牙 API 错误码对照表。
• 常见问题及解决方法，请参见下文 蓝牙 API FAQ。

版本需求

蓝牙类型	支付宝客户端版本需求	Android 或 iOS 版本需求
BLE 低功耗蓝牙	支付宝客户端 10.0.18 或更高版本，若版本较低，建议做 兼容处理。	Android： 5.0 及以上版本iOS：无版本需求
传统蓝牙	支付宝客户端 10.0.18 或更高版本，若版本较低，建议做 兼容处理。my.startBluetoothDevicesDiscovery 方法的 allowDuplicatesKey 和 interval 参数，从支付宝客户端 10.0.20 版本开始支持。	-
iBeacon	支付宝客户端 10.1.8 或更高版本，若版本较低，建议做 兼容处理。	-

基本流程

低功耗蓝牙流程图

传统蓝牙流程图

蓝牙 API

蓝牙类型	名称	功能说明
低功耗蓝牙	my.connectBLEDevice	连接低功耗蓝牙设备。
	my.disconnectBLEDevice	断开与低功耗蓝牙设备的连接。
	my.getBLEDeviceCharacteristics	获取蓝牙设备所有 characteristic（特征值）。
	my.getBLEDeviceServices	获取所有已发现的蓝牙设备，包括已经和本机处于连接状态的设备。
	my.notifyBLECharacteristicValueChange	启用低功耗蓝牙设备特征值变化时的 notify 功能。
	my.offBLECharacteristicValueChange	取消监听低功耗蓝牙设备的特征值变化的事件。
	my.offBLEConnectionStateChanged	取消低功耗蓝牙连接状态变化事件的监听。
	my.onBLECharacteristicValueChange	监听低功耗蓝牙设备的特征值变化的事件。
	my.onBLEConnectionStateChanged	监听低功耗蓝牙连接的错误事件，包括设备丢失，连接异常断开等。
	my.readBLECharacteristicValue	读取低功耗蓝牙设备特征值中的数据。
	my.writeBLECharacteristicValue	向低功耗蓝牙设备特征值中写入数据。
传统蓝牙	my.closeBluetoothAdapter	关闭本机蓝牙模块。
	my.getBluetoothAdapterState	获取本机蓝牙模块状态。
	my.getBluetoothDevices	获取所有已发现的蓝牙设备，包括已经和本机处于连接状态的设备。
	my.getConnectedBluetoothDevices	获取处于已连接状态的设备。
	my.offBluetoothAdapterStateChange	移除本机蓝牙状态变化的事件的监听。
	my.offBluetoothDeviceFound	移除寻找到新的蓝牙设备事件的监听。
	my.onBluetoothDeviceFound	搜索到新的蓝牙设备时触发此事件。
	my.onBluetoothAdapterStateChange	监听本机蓝牙状态变化的事件。
	my.openBluetoothAdapter	初始化小程序蓝牙适配器。
	my.startBluetoothDevicesDiscovery	开始搜寻附近的蓝牙外围设备。
	my.stopBluetoothDevicesDiscovery	停止搜寻附近的蓝牙外围设备。
iBeacon	my.getBeacons	获取已经搜索到的 iBeacon 设备。
	my.onBeaconServiceChange	监听 iBeacon 服务的状态变化。
	my.onBeaconUpdate	监听 iBeacon 设备的更新事件。
	my.startBeaconDiscovery	开始搜索附近的 iBeacon 设备。
	my.stopBeaconDiscovery	停止搜索附近的 iBeacon 设备。

示例代码

//初始化
my.openBluetoothAdapter({
  success: (res) => {
    console.log(res);
  }
});


//注册发现事件
my.onBluetoothDeviceFound({
  success: (res) => {
    let device = res.devices[0];


    //连接发现的设备
    my.connectBLEDevice({
      deviceId: deviceId,
      success: (res) => {
        console.log(res)
      },
      fail:(res) => {
      },
      complete: (res)=>{
      }
    });


    //停止搜索
    my.stopBluetoothDevicesDiscovery({
      success: (res) => {
        console.log(res)
      },
      fail:(res) => {
      },
      complete: (res)=>{
      }
    });
  }
});

    
//注册连接事件
my.onBLEConnectionStateChanged({
  success: (res) => {
    console.log(res);
    if (res.connected) {
        //开始读写notify等操作
        my.notifyBLECharacteristicValueChange({
          deviceId: deviceId,
          serviceId: serviceId,
          characteristicId: characteristicId,
          success: (res) => {
            console.log(res)
          },
          fail:(res) => {
          },
          complete: (res)=>{
          }
        });
    }
  }
});


//注册接收read或notify的数据
my.onBLECharacteristicValueChange({
  success: (res) => {
    console.log(res);
  }
});


//开始搜索
my.startBluetoothDevicesDiscovery({
  services: ['fff0'],
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});


//断开连接
my.disconnectBLEDevice({
  deviceId: deviceId,
  success: (res) => {
    console.log(res)
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});


//注销事件
my.offBluetoothDeviceFound();
my.offBLEConnectionStateChanged();
my.offBLECharacteristicValueChange();


//退出蓝牙模块
my.closeBluetoothAdapter({
  success: (res) => {
  },
  fail:(res) => {
  },
  complete: (res)=>{
  }
});

蓝牙 API 错误码对照表

错误码	说明	解决方案
10000	未初始化蓝牙适配器。	调用 my.openBluetoothAdapter，进行蓝牙适配器初始化。
10001	当前蓝牙适配器不可用。	检查当前设备对 BLE 的支持情况，并开启蓝牙功能。
10002	没有找到指定设备。	检查 deviceId，并确认已开启目标蓝牙外设的广播。
10003	连接失败。	检查 deviceId，并确认已开启目标蓝牙外设的广播。
10004	没有找到指定服务。	检查 serviceId，并确认目标外设已拥有该服务。
10005	没有找到指定特征值。	确保 characteristicId 正确、检查目标外设特定 service 下已具备该特征。
10006	当前连接已断开。	连接断开，重新连接。
10007	当前特征值不支持此操作。	检查特征值具备读、写、通知等功能。
10008	其余所有系统上报的异常。	其他未知错误，具体问题具体分析。
10009	Android 系统特有，系统版本低于 4.3 不支持 BLE。	提示用户该安卓系统版本不支持使用 。
10010	没有找到指定描述符。	使用正确的 serviceId、characteristicId。
10011	设备 ID 不可用，或为空。	使用正确的 deviceId。
10012	服务 ID 不可用，或为空。	使用正确的 serviceId。
10013	特征 ID 不可用，或为空。	使用正确的 characteristicId。
10014	发送的数据为空或格式错误。	确保写数据或者 HEX 转化正确。
10015	操作超时。	重新操作。
10016	缺少参数。	检查调用的参数，并重新操作。
10017	写入特征值失败。	写失败。确保外设特征支持写操作，不要断开连接。
10018	读取特征值失败。	读失败。确保外设特征支持读操作，不要断开连接。

蓝牙 API FAQ

Q：调用 my.writeBLECharacteristicValue 的返回值是空对象吗？

A：不是，调用此 API 返回的是您写入成功的值。

Q：调用 my.onBLECharacteristicValueChange 为何监听不到？一定要先写入才能监听到吗？

A：是的，调用此 API 需要先写入才能监听到。为防止多次注册事件监听导致一次事件多次回调，建议每次调用 on 方法监听事件之前，先调用 off 方法，关闭之前的事件监听。

Q：调用 my.writeBLECharacteristicValue 为何报错10014？

A：10014 错误是由于发送的数据为空或者格式错误导致，建议检查写入的数据或 HEX 转化是否有错误。

Q：调用 my.writeBLECharacteristicValue 写入特征值，使用 16 进制的数组可以吗？

A：不可以，写入特征值需要使用 16 进制的字符串，并限制在 20 字节内。

Q：安卓和 iOS 获取到的 deviceId 格式分别是什么样的？

A：

• Android 获取到的是蓝牙的 mac 地址。如：11:22:33:44:55:66
• iOS 获取到的是蓝牙的 UUID。如：00000000-0000-0000-0000-000000000000

Q：调用 my.startBluetoothDevicesDiscovery 接口为何搜索不到设备？

A：请确保设备已发出广播。若接口传入 services，请确保设备的广播内容中包含 service 的 UUID。

Q：调用蓝牙 API 时如果不开启 GPS 定位，部分机型会报错：定位服务未开启。连接不了蓝牙？

A：小程序蓝牙功能需要依赖 GPS 定位，因为大概 5 分之一的手机蓝牙需要依赖 GPS。 建议接入蓝牙时先引导用户打开 GPS 定位服务。

Q：如何解决连接设备失败?

A：请确保传入的 deviceId 正确，并且设备发出的信号足够强。在信号弱的情况下，可能会出现连接设备失败。

Q：如何解决写 / 读数据失败？

A：

• 请确保传入的 deviceId、serviceId、characteristicId 格式正确。
• deviceId 已连接上（可调用 my.onBLEConnectionStateChanged 监听连接状态的变化；调用 my.getConnectedBluetoothDevices 获取处于已连接状态的设备。）
• 在连接状态下写入方法。
• 检查 characteristicId 属于此 service。
• 此特征值支持写 / 读。

Q：如何收到数据通知？

A：

• 请确保已调用 my.notifyBLECharacteristicValueChange 方法，并且传入的参数正确。
• 传入的 characteristicId 特征值支持 notify 或 indicate 操作。
• 确保硬件已发出通知。
• 注意基本流程顺序，在连接之后就调用 my.notifyBLECharacteristicValueChange 方法。

Q：为何事件回调会多次被调用？

A：由于多次匿名函数注册监听了同一事件。所以建议在每次调用 on 方法监听事件之前，先调用 off 方法关闭之前的事件监听。