Guide to Avoiding Pitfalls in WeChat Bluetooth Mini Program Development: Compatibility Issues between Android and iOS
Recently, at the request of our company, we developed a mini program where the low-power Bluetooth data acquisition feature is a key component. Initially, we used Android devices for real-device debugging, and everything progressed smoothly. However, as the product neared release, various issues arose when colleagues tested it on Apple devices. Here, I will detail these pitfalls to help developers avoid similar issues in future development.
1. Bluetooth Name Rendering Issues
Problem Description
During development and debugging on the Android side, the Bluetooth information retrieved showed that the <span>name</span> and <span>localName</span> were identical. Based on this, we directly used <span>name</span> in the code to display the Bluetooth device name, which worked fine during Android testing. However, when switching to the iOS side, the situation was completely different. The <span>name</span> and <span>localName</span> on iOS differed, resulting in the Bluetooth name displayed in the iOS mini program being a strange character combination like <span>“E04-BT_V1.”</span>, which did not match the expected name. If this is not known in advance, it can easily lead to iOS users being unable to accurately identify the Bluetooth device, severely affecting the user experience.
Solution
In the code, make judgments based on the different systems and dynamically select the appropriate name field for display. After obtaining the Bluetooth device information, you can use <span>wx.getSystemInfoSync()</span> to get the system information and decide whether to use <span>name</span> or <span>localName</span> based on the system type (<span>system field</span>). The sample code is as follows:
wx.getBLEDeviceInfo({
deviceId: deviceId,
success: function (res) {
const systemInfo = wx.getSystemInfoSync();
let displayName;
if (systemInfo.system.indexOf('iOS') > -1) {
displayName = res.localName;
} else {
displayName = res.name;
}
// Use displayName for interface display
}
});2. Data Writing Issues
Problem Description
After resolving the Bluetooth name display error, we attempted to send data but kept receiving error messages. In the project, for consistency and convenience, the default <span>uuid</span> for connecting to the mini program product is <span>“0000FFF0-0000-1000-8000-00805F9B34FB”</span>. We hardcoded the <span>serviceId</span> and <span>characteristicId</span> in the code, but this approach did not work properly on iOS. After searching various technical platforms without success, we finally identified the root of the problem through repeated study of the official documentation and continuous experimentation.
Solution
In iOS, before calling <span>wx.writeBLECharacteristicValue({})</span> for data writing, you must first call <span>wx.getBLEDeviceServices({})</span> and <span>wx.getBLEDeviceCharacteristics({})</span> to obtain device service and characteristic information. The reference code is as follows:
wx.getBLEDeviceServices({
deviceId:devv,
success (res) {
wx.getBLEDeviceCharacteristics({
deviceId:devv,
serviceId:res.services[1].uuid,
success (res) {
// Handle the obtained characteristic information here
},
fail(res) {
console.error('getBLEDeviceCharacteristics===', res)
}
})
},
fail (e){
console.log('fail services:', res)
}
})When writing data in iOS, the <span>serviceId</span> and <span>characteristicId</span> must be in uppercase letters. The correct calling example is:
wx.writeBLECharacteristicValue({
deviceId: devv,
serviceId: "0000FFF0-0000-1000-8000-00805F9B34FB",
characteristicId: "0000FFF2-0000-1000-8000-00805F9B34FB",
})3. Data Reading Issues
Problem Description
In the Android system, directly nesting <span>wx.writeBLECharacteristicValue({})</span> with <span>wx.notifyBLECharacteristicValueChange({})</span> and <span>wx.onBLECharacteristicValueChange(function (res) {})</span> allows for smooth reading of data sent from the other end. However, in the iOS system, if only the above operations are executed, the data cannot be updated properly; additional operations must be performed to obtain the latest Bluetooth transmission data.
Solution
In the iOS system, in addition to the operations for the Android system, you need to call <span>wx.readBLECharacteristicValue({})</span> at the appropriate time to trigger data updates and readings. You can call <span>wx.readBLECharacteristicValue({})</span><code> in the success callback of <code><span>wx.notifyBLECharacteristicValueChange({})</span><code>. The sample code is as follows:
wx.writeBLECharacteristicValue({
deviceId: devv,
serviceId: "0000FFF0-0000-1000-8000-00805F9B34FB",
characteristicId: "0000FFF2-0000-1000-8000-00805F9B34FB",
value:that.data.buffer,
success: function (res) {
wx.notifyBLECharacteristicValueChange({
state: true,
deviceId:devv,
serviceId:"0000FFF0-0000-1000-8000-00805F9B34FB",
characteristicId: "0000FFF1-0000-1000-8000-00805F9B34FB",
success: function (res) {
wx.readBLECharacteristicValue({
deviceId: devv,
serviceId: "0000FFF0-0000-1000-8000-00805F9B34FB",
characteristicId: "0000FFF1-0000-1000-8000-00805F9B34FB",
success: function (readRes) {
wx.onBLECharacteristicValueChange(function (res) {
console.log( res)
})
}
})
}
})
}
})4. UUID Permissions and Usage in iOS
Problem Description
In the iOS system, different UUIDs obtained through <span>wx.getBLEDeviceServices({})</span> correspond to different permissions. For example, <span>0000FFF3</span> is generally used for write operations in <span>wx.writeBLECharacteristicValue({})</span><code> characteristic values. If you are unaware of the permissions associated with each <code><span>uuid</span>, arbitrary usage may lead to data transmission errors, failing to meet actual business needs.
Solution
Before development, thoroughly review the Bluetooth service documentation provided by the device manufacturer to clarify the specific permissions and uses of each <span>uuid</span>. In the code, select the corresponding <span>uuid</span> based on business needs (such as data writing, reading, etc.) to ensure the accuracy and stability of data transmission. Additionally, you can organize the relevant information of the UUIDs into a <span>configuration file or constants</span> for easier code maintenance and modification.
Conclusion
In WeChat Bluetooth mini program development, there are significant differences in Bluetooth functionality implementation between Android and iOS systems. Developers must not rely solely on debugging in a single system; comprehensive testing across multiple systems and devices is essential. Additionally, deeply studying the official documentation and actively attempting to solve problems while summarizing experiences will effectively help avoid various pitfalls and create stable and reliable Bluetooth mini program functionalities.
I hope the above content is helpful to everyone, and developers are welcome to share experiences and discuss issues in the comments section!
Share, like, and check it out?