# Device
# Battery
# getBatteryInfoSync
getBatteryInfoSync()
The synchronous version of ft.getBatteryInfo
Return Value
Object res
| Property | Type | Description |
|---|---|---|
| level | string | Device battery level, range 1 - 100 |
| isCharging | boolean | Whether the device is currently charging |
# getBatteryInfo
getBatteryInfo(Object object)
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed on both success and failure) |
object.success callback function
Parameter
Object object
| Property | Type | Description |
|---|---|---|
| level | string | Device battery level, range 1 - 100 |
| isCharging | boolean | Whether the device is currently charging |
# Clipboard
# setClipboardData
Supported from Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38 onwards, requires Extension SDK
setClipboardData(Object object)
Sets the content of the system clipboard.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| data | string | Yes | Content of the clipboard | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed on both success and failure) |
Sample Code
ft.setClipboardData({
data: 'data',
success(res) {
ft.getClipboardData({
success(res) {
console.log(res.data) // data
}
})
}
})
# getClipboardData
Supported from Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38 onwards, requires Extension SDK
getClipboardData(Object object)
Gets the content of the system clipboard.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed on both success and failure) |
object.success callback function
Parameter
Object object
| Property | Type | Description |
|---|---|---|
| data | string | Content of the clipboard |
Sample Code
ft.getClipboardData({
success(res) {
console.log(res.data)
}
})
# Network
# onNetworkStatusChange
Supported from Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38 onwards
onNetworkStatusChange(function callback)
Listens for network status change events.
Parameters
function callback
Callback function for network status change events
Parameter
Object res
| Property | Type | Description |
|---|---|---|
| isConnected | boolean | Whether there is a current network connection |
| networkType | string | Network type |
Valid values for res.networkType
| Value | Description |
|---|---|
| wifi | Wi-Fi network |
| 2g | 2G network |
| 3g | 3G network |
| 4g | 4G network |
| unknown | Unknown network |
| none | No network |
Sample Code
ft.onNetworkStatusChange(function (res) {
console.log(res.isConnected)
console.log(res.networkType)
})
# offNetworkStatusChange
offNetworkStatusChange(function callback)
Cancels listening for network status change events; if the parameter is empty, all event listeners are removed.
Parameters
function callback
Callback function for network status change events
# getNetworkType
Supported from Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38 onwards
getNetworkType(Object object)
Gets the network type.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed on both success and failure) |
object.success callback function
Parameter
Object res
| Property | Type | Description |
|---|---|---|
| networkType | string | Network type |
Valid values for res.networkType
| Value | Description |
|---|---|
| wifi | Wi-Fi network |
| 2g | 2G network |
| 3g | 3G network |
| 4g | 4G network |
| unknown | Unknown network |
| none | No network |
Sample Code
ft.getNetworkType({
success(res) {
const networkType = res.networkType
}
})
# Screen
# setScreenBrightness
Supported from Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38 onwards
setScreenBrightness(Object object)
Sets the screen brightness.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| value | number | Yes | Screen brightness value, range 0 ~ 1. 0 is the dimmest, 1 is the brightest | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed on both success and failure) |
# setKeepScreenOn
Supported from Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38 onwards
setKeepScreenOn(Object object)
Sets whether to keep the screen always on.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| keepScreenOn | boolean | Yes | Whether to keep the screen always on | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed on both success and failure) |
Sample Code
ft.setKeepScreenOn({
keepScreenOn: true
})
# onUserCaptureScreen
onUserCaptureScreen(function callback)
Listens for user-initiated screenshot events. Triggered when the user takes a screenshot using the system screenshot key. Only one listener can be registered.
Parameters
function callback
Callback function for user-initiated screenshot events.
Example Code
ft.onUserCaptureScreen(function (res) {
console.log('User has taken a screenshot')
})
# offUserCaptureScreen
offUserCaptureScreen(function callback)
User-initiated screenshot event. Cancels the event listener.
Parameters
function callback
Callback function for user-initiated screenshot events.
# getScreenBrightness
Supported from Base Library 1.3.9, iOS SDK 2.1.23, and Android SDK 2.1.38 onwards
getScreenBrightness(Object object)
Gets the screen brightness.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed on both success and failure) |
object.success Callback Function
Parameters
Object object
| Property | Type | Description |
|---|---|---|
| value | number | Screen brightness value, ranging from 0 to 1, where 0 is the darkest and 1 is the brightest |
# Keyboard
# showKeyboard
showKeyboard(Object object)
Displays the keyboard.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| defaultValue | string | Yes | Default value displayed in the keyboard input box | |
| maxLength | number | Yes | Maximum length of text in the keyboard | |
| multiple | boolean | Yes | Whether it is multi-line input | |
| confirmHold | boolean | Yes | Whether the keyboard retracts when the "Done" button is clicked | |
| confirmType | string | Yes | Type of the confirm button at the bottom right of the keyboard, affecting only the text content of the button | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed on both success and failure) |
Legal values for object.confirmType
| Value | Display Name |
|---|---|
| done | Done |
| next | Next |
| search | Search |
| go | Go |
| send | Send |
Example Code
ft.showKeyboard({
defaultValue: 'input text',
maxLength: 50,
multiple: false,
confirmHold: false,
confirmType: 'go',
complete: res => {
console.log('showKeyboard res', res)
}
})
# updateKeyboard
updateKeyboard(Object object)
Updates the input box content.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| value | string | Yes | Updated value of the input box | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed on both success and failure) |
Example Code
ft.updateKeyboard({
value: 'some new value',
complete: res => {
console.log('updateKeyboard res', res)
}
})
# hideKeyboard
hideKeyboard(Object object)
After invoking the keyboard with showKeyboard, manually call this interface to hide the keyboard.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed on both success and failure) |
Example Code
ft.hideKeyboard({
complete: res => {
console.log('hideKeyboard res', res)
}
})
# onKeyboardInput
onKeyboardInput(function callback)
Listens for keyboard input events.
Parameters
function callback
Listener function for keyboard input events.
Parameters
object res
| Property | Type | Description |
|---|---|---|
| value | string | Current value entered in the keyboard |
Example Code
ft.onKeyboardInput(res => {
console.log(res.value)
})
# onKeyboardHeightChange
onKeyboardHeightChange(function callback)
Listens for changes in keyboard height.
Parameters
function callback
Listener function for keyboard height change events.
Parameters
object res
| Property | Type | Description |
|---|---|---|
| height | number | Height of the keyboard |
Example Code
ft.onKeyboardHeightChange(res => {
console.log(res.height)
})
# onKeyboardConfirm
onKeyboardConfirm(function callback)
Listens for the event when the user clicks the Confirm button on the keyboard.
Parameters
function callback
Listener function for the event when the user clicks the Confirm button on the keyboard.
Parameters
object res
| Property | Type | Description |
|---|---|---|
| value | string | Current value entered in the keyboard |
Example Code
ft.onKeyboardConfirm(res => {
console.log(res.value)
})
# onKeyboardComplete
onKeyboardComplete(function callback)
Listens for the event when the keyboard is dismissed.
Parameters
function callback
Listener function for the event when the keyboard is dismissed.
Parameters
object res
| Property | Type | Description |
|---|---|---|
| value | string | Current value entered in the keyboard |
Example Code
ft.onKeyboardComplete(res => {
console.log(res.value)
})
# offKeyboardInput
offKeyboardInput(function callback)
Unlisten to keyboard input events.
Parameters
function callback
The callback function passed in onKeyboardInput.
# offKeyboardHeightChange
offKeyboardHeightChange(function callback)
Unlisten to keyboard height change events.
Parameters
function callback
The callback function passed in onKeyboardHeightChange.
# offKeyboardConfirm
offKeyboardConfirm(function callback)
Unlisten to the event triggered when the user clicks the Confirm button on the keyboard.
Parameters
function callback
The callback function passed in onKeyboardConfirm.
# offKeyboardComplete
offKeyboardComplete(function callback)
Unlisten to the event triggered when the keyboard is dismissed.
Parameters
function callback
The callback function passed in onKeyboardComplete.
# Accelerometer
# stopAccelerometer
stopAccelerometer(Object object)
Stop listening to accelerometer data.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed whether the call succeeds or fails) |
Example Code
ft.stopAccelerometer()
# startAccelerometer
startAccelerometer(Object object)
Start listening to accelerometer data.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| interval | string | normal | No | Execution frequency of the accelerometer data callback function |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed whether the call succeeds or fails) |
Valid values for object.interval
| Value | Description |
|---|---|
| game | Suitable for updating game callbacks, around 20ms/interval |
| ui | Suitable for updating UI callbacks, around 60ms/interval |
| normal | Normal callback frequency, around 200ms/interval |
Example Code
ft.startAccelerometer({
interval: 'game'
})
# onAccelerometerChange
onAccelerometerChange(function callback)
Listen to accelerometer data events. The frequency depends on the interval parameter of ft.startAccelerometer(). Listening will automatically begin after the API is called.
Parameters
function callback
Callback function for accelerometer data events.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| x | number | X-axis |
| y | number | Y-axis |
| z | number | Z-axis |
Example Code
ft.onAccelerometerChange(callback)
# offAccelerometerChange
offAccelerometerChange(function callback)
Unlisten to accelerometer data events. If the parameter is empty, all event listeners will be removed.
Parameters
function callback
Callback function for accelerometer data events.
# Compass
# stopCompass
stopCompass(Object object)
Stop listening to compass data.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed whether the call succeeds or fails) |
Example Code
ft.stopCompass()
# startCompass
startCompass(Object object)
Start listening to compass data.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed whether the call succeeds or fails) |
Example Code
ft.startCompass()
# onCompassChange
onCompassChange(function callback)
Listen to compass data change events. Frequency: 5 times/second. Listening will automatically begin after the API is called. You can use ft.stopCompass to stop listening.
Parameters
function callback
Callback function for compass data change events.
Parameters
Object object
| Property | Type | Description |
|---|---|---|
| direction | number | Degrees indicating the facing direction |
| accuracy | number/string | Accuracy |
Example Code
ft.onCompassChange(callback)
Differences in accuracy between iOS/Android
Due to platform differences, the value of accuracy differs between iOS and Android.
- iOS:
accuracyis a number type value representing the deviation from magnetic north. A value of 0 means the device is pointing to magnetic north, 90 means east, 180 means south, and so on. - Android:
accuracyis a string type enumeration value.
| Value | Description |
|---|---|
| high | High precision |
| medium | Medium precision |
| low | Low precision |
| no-contact | Unreliable, sensor connection lost |
| unreliable | Unreliable, unknown reason |
| unknow ${value} | Unknown precision enumeration value, meaning that the value returned by this Android system at this time is not a standard precision enumeration value |
# offCompassChange
offCompassChange(function callback)
Unlisten to compass data change events. If the parameter is empty, all event listeners will be removed.
Parameters
function callback
Callback function for compass data change events.
# Device Orientation
# stopDeviceMotionListening
stopDeviceMotionListening(Object object)
Stop listening to changes in device orientation.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed whether the call succeeds or fails) |
# startDeviceMotionListening
startDeviceMotionListening(Object object)
Start listening to changes in device orientation.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| interval | string | normal | No | Execution frequency of the device orientation change callback function |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed whether the call succeeds or fails) |
Valid values for object.interval
| Value | Description |
|---|---|
| game | Suitable for updating game callbacks, around 20ms/interval |
| ui | Suitable for updating UI callbacks, around 60ms/interval |
| normal | Normal callback frequency, around 200ms/interval |
# onDeviceMotionChange
onDeviceMotionChange(function callback)
Listen to device orientation change events. The frequency depends on the interval parameter of ft.startDeviceMotionListening(). You can use ft.stopDeviceMotionListening() to stop listening.
Parameters
function callback
Callback function for device orientation change events.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| alpha | number | When the phone's X/Y coordinates align with Earth's X/Y, the angle rotated around the Z-axis is alpha, ranging from [0, 2*PI). Counterclockwise rotation is positive. |
| beta | number | When the phone's Y/Z coordinates align with Earth's Y/Z, the angle rotated around the X-axis is beta. Ranges from [-1*PI, PI). Rotation towards the Earth's surface is positive. It may also be positive when rotating towards the user. |
| gamma | number | When the phone's X/Z coordinates align with Earth's X/Z, the angle rotated around the Y-axis is gamma. Ranges from [-1*PI/2, PI/2). Rotation towards the Earth's surface on the right side is positive. |
# offDeviceMotionChange
offDeviceMotionChange(function callback)
Unlisten to device orientation change events. If the parameter is empty, all event listeners will be removed.
Parameters
function callback
Callback function for device orientation change events.
# Screen Rotation
# setDeviceOrientation
setDeviceOrientation(Object object)
Switch between landscape and portrait screen orientations.
After the interface call succeeds, it will trigger the onDeviceOrientationChange event.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| value | string | Yes | Indicates switching to landscape or portrait mode | |
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call | |
| complete | function | No | Callback function when the interface call ends (executed whether the call succeeds or fails) |
Valid values for object.value
| Value | Description |
|---|---|
| landscape | Landscape |
| portrait | Portrait |
Sample Code
ft.setDeviceOrientation({
value: 'portrait',
complete: res => {
console.log('setDeviceOrientation res', res)
}
})
# onDeviceOrientationChange
onDeviceOrientationChange(function callback)
Listen for screen orientation change events.
Parameters
function callback
The listener function for screen orientation change events.
Parameters
object res
| Property | Type | Description |
|---|---|---|
| value | string | The new screen orientation after the switch |
Values for res.value
| Name | Description |
|---|---|
| landscape | Landscape in the normal direction, with the HOME button on the right side of the screen as the normal direction |
| landscapeReverse | Landscape in the reverse direction, with the HOME button on the left side of the screen as the reverse direction |
Sample Code
ft.onDeviceOrientationChange(res => {
console.log(res.value)
})
# offDeviceOrientationChange
offDeviceOrientationChange(function callback)
Stop listening for screen orientation change events.
Parameters
function callback
The callback function passed into onDeviceOrientationChange.
# Gyroscope
# stopGyroscope
stopGyroscope(Object object)
Stop listening for gyroscope data.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call | |
| complete | function | No | Callback function when the interface call ends (executed whether the call succeeds or fails) |
# startGyroscope
startGyroscope(Object object)
Start listening for gyroscope data.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| interval | string | normal | No | Execution frequency of the gyroscope data callback function |
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call | |
| complete | function | No | Callback function when the interface call ends (executed whether the call succeeds or fails) |
Valid values for object.interval
| Value | Description |
|---|---|
| game | Suitable for updating game callbacks at around 20ms per time |
| ui | Suitable for updating UI callbacks at around 60ms per time |
| normal | Normal callback frequency at around 200ms per time |
# onGyroscopeChange
onGyroscopeChange(function callback)
Listen for gyroscope data change events. Frequency depends on the interval parameter of ft.startGyroscope(). Listening can be stopped using ft.stopGyroscope().
Parameters
function callback
Callback function for gyroscope data change events.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| x | number | Angular velocity on the x-axis |
| y | number | Angular velocity on the y-axis |
| z | number | Angular velocity on the z-axis |
# offGyroscopeChange
offGyroscopeChange(function callback)
Stop listening for gyroscope data change events.
Parameters
function callback
Callback function for gyroscope data change events.
# Scan Code
# scanCode
Supported from Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38 onwards
scanCode(Object object)
Invoke the client's scan code interface to scan codes.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| onlyFromCamera | boolean | false | No | Whether scanning is only allowed from the camera, disallowing image selection from the album |
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call (when authorization fails, returns error message: fail unauthorized user did not grant camera permission) | |
| complete | function | No | Callback function when the interface call ends (executed whether the call succeeds or fails) |
object.success callback function
Parameters
Object res
Sample Code
// Allow scanning from both camera and album
ft.scanCode({
success(res) {
console.log(res)
}
})
// Only allow scanning from the camera
ft.scanCode({
onlyFromCamera: true,
success(res) {
console.log(res)
}
})
Note
- Interface authorization failure (iOS):
- If the user denies authorization, it will return the error message: unauthorized, user did not grant camera permission
- If the Host-App prohibits Mini-Programs from actively requesting permissions, it will return the error message: unauthorized disableauthorized, SDK is prohibited from requesting camera permissions
- Interface authorization failure (Android):
- If the user denies authorization, it will return the error message: fail unauthorized user did not grant camera permission
- If the Host-App prohibits Mini-Programs from actively requesting permissions, it will return the error message: unauthorized disableauthorized SDK is prohibited from initiating permission requests
# Vibration
# vibrateShort
Supported from Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38 onwards
vibrateShort(Object object)
Make the phone vibrate for a short period of time (15 ms). Effective only on iPhone 7 / 7 Plus and above, and Android devices.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call (when authorization fails, returns error message: fail unauthorized user did not grant vibration permission) | |
| complete | function | No | Callback function when the interface call ends (executed whether the call succeeds or fails) |
Note
- Interface authorization failure (Android):
- If the user denies authorization, it will return the error message: unauthorized user did not grant vibration permission
- If the Host-App prohibits Mini-Programs from actively requesting permissions, it will return the error message: unauthorized disableauthorized SDK is prohibited from initiating permission requests
# vibrateLong
Supported from Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38 onwards
vibrateLong(Object object)
Make the phone vibrate for a longer period of time (400 ms).
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful interface call | |
| fail | function | No | Callback function for failed interface call (when authorization fails, returns error message: fail unauthorized user did not grant vibration permission) | |
| complete | function | No | Callback function when the interface call ends (executed whether the call succeeds or fails) |
Note
- Interface authorization failure (Android):
- If the user denies authorization, it will return the error message: unauthorized user did not grant vibration permission
- If the Host-App prohibits Mini-Programs from actively requesting permissions, it will return the error message: unauthorized disableauthorized SDK is prohibited from initiating permission requests
# Bluetooth - General
# stopBluetoothDevicesDiscovery(Object object)
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Stops searching for nearby Bluetooth peripheral devices. If the required Bluetooth device has already been found and there is no need to continue searching, it is recommended to call this interface to stop the Bluetooth search.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed whether the call succeeds or fails) |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| -1 | already connected | Already connected |
| 10000 | not init | Bluetooth adapter not initialized |
| 10001 | not available | Current Bluetooth adapter is unavailable |
| 10002 | no device | Specified device not found |
| 10003 | connection fail | Connection failed |
| 10004 | no service | Specified service not found |
| 10005 | no characteristic | Specified characteristic not found |
| 10006 | no connection | Current connection has been disconnected |
| 10007 | property not support | Current characteristic does not support this operation |
| 10008 | system error | All other exceptions reported by the system |
| 10009 | system not support | Android-specific, system versions below 4.3 do not support BLE |
| 10012 | operate time out | Connection timeout |
| 10013 | invalid_data | Connection deviceId is empty or incorrectly formatted |
# startBluetoothDevicesDiscovery(Object object)
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Starts searching for nearby Bluetooth peripheral devices.
This operation consumes significant system resources. It is recommended to call ft.stopBluetoothDevicesDiscovery to stop the search as soon as the desired device is found.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| services | Array.string | No | List of UUIDs of the main Bluetooth device services to be searched (supports 16/32/128-bit UUIDs). Some Bluetooth devices broadcast their main service UUIDs. If this parameter is set, only Bluetooth devices with corresponding UUIDs in their broadcast packets will be searched. It is recommended to use this parameter to filter out other irrelevant Bluetooth devices. | |
| allowDuplicatesKey | boolean | false | No | Whether to allow duplicate reporting of the same device. If allowed, the onBlueToothDeviceFound method will report the same device multiple times, but the RSSI values may differ. |
| interval | number | 0 | No | Interval for reporting devices, in ms. A value of 0 means new devices are reported immediately upon discovery; otherwise, reports are made at the specified interval. |
| powerLevel | string | medium | No | Scanning mode; higher modes scan faster but consume more power. |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed whether the call succeeds or fails) |
Valid values for object.powerLevel
| Value | Description | Minimum Version |
|---|---|---|
| low | Low | |
| medium | Medium | |
| high | High |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| -1 | already connected | Already connected |
| 10000 | not init | Bluetooth adapter not initialized |
| 10001 | not available | Current Bluetooth adapter is unavailable |
| 10002 | no device | Specified device not found |
| 10003 | connection fail | Connection failed |
| 10004 | no service | Specified service not found |
| 10005 | no characteristic | Specified characteristic not found |
| 10006 | no connection | Current connection has been disconnected |
| 10007 | property not support | Current characteristic does not support this operation |
| 10008 | system error | All other exceptions reported by the system |
| 10009 | system not support | Android-specific, system versions below 4.3 do not support BLE |
| 10012 | operate time out | Connection timeout |
| 10013 | invalid_data | Connection deviceId is empty or incorrectly formatted |
# openBluetoothAdapter(Object object)
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Initializes the Bluetooth module. On iOS, when enabling host/peripheral (peripheral device) mode, it must be called once for each mode, specifying the corresponding mode.
Parameters
Object object
| Property | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| mode | string | central | No | Bluetooth mode, can act as either a host or peripheral device, only required for iOS. | |
| success | function | No | Callback function for successful API call | ||
| fail | function | No | Callback function for failed API call | ||
| complete | function | No | Callback function for when the API call ends (executed whether the call succeeds or fails) |
Valid values for object.mode
| Value | Description | Minimum Version |
|---|---|---|
| central | Host mode | |
| peripheral | Peripheral (Peripheral Device) mode |
# Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| -1 | already connected | Already connected |
| 10000 | not init | Bluetooth adapter not initialized |
| 10001 | not available | Current Bluetooth adapter is unavailable |
| 10002 | no device | Specified device not found |
| 10003 | connection fail | Connection failed |
| 10004 | no service | Specified service not found |
| 10005 | no characteristic | Specified characteristic not found |
| 10006 | no connection | Current connection has been disconnected |
| 10007 | property not support | Current characteristic does not support this operation |
| 10008 | system error | All other exceptions reported by the system |
| 10009 | system not support | Android-specific, system versions below 4.3 do not support BLE |
| 10012 | operate time out | Connection timeout |
| 10013 | invalid_data | Connection deviceId is empty or incorrectly formatted |
# state parameter returned by object.fail callback function (iOS only)
| Status Code | Description |
|---|---|
| 0 | Unknown |
| 1 | Resetting |
| 2 | Not supported |
| 3 | Unauthorized |
| 4 | Not enabled |
# Note
- Other Bluetooth-related APIs must be used after calling
openBluetoothAdapter. Otherwise, the API will return an error (errCode=10000). - If the user's Bluetooth switch is off or the phone does not support Bluetooth functionality, calling
openBluetoothAdapterwill return an error (errCode=10001), indicating that the phone's Bluetooth functionality is unavailable. At this point, the Mini-Program's Bluetooth module has been initialized, and you can listen for changes in the phone's Bluetooth status viaonBluetoothAdapterStateChange, or call all Bluetooth module APIs.
Note
- Interface authorization failure (iOS):
- If the Host-App prohibits the Mini-Program from actively requesting permissions, it will return the error message: unauthorized disableauthorized, meaning the SDK is prohibited from requesting Bluetooth permissions.
# onBluetoothDeviceFound(function callback)
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Listens for events when a new device is discovered.
# Parameters
function callback
Callback function for the event when a new device is discovered.
Parameters
object res
| Property | Type | Description |
|---|---|---|
| devices | Array.Object | List of newly discovered devices |
Structure of res.devices
| Property | Type | Description |
|---|---|---|
| name | string | Bluetooth device name, some devices may not have one |
| deviceId | string | Bluetooth device ID |
| RSSI | number | Signal strength of the current Bluetooth device, in dBm |
| advertisData | ArrayBuffer | ManufacturerData segment in the broadcast data segment of the current Bluetooth device. |
| advertisServiceUUIDs | Array.string | ServiceUUIDs segment in the broadcast data segment of the current Bluetooth device |
| localName | string | LocalName segment in the broadcast data segment of the current Bluetooth device |
| serviceData | Object | ServiceData segment in the broadcast data segment of the current Bluetooth device |
# Note
- If a device is returned in the
onBluetoothDeviceFoundcallback, this device will be added to the array obtained by thegetBluetoothDevicesinterface. - On some Android models, location permission is required to discover devices; ensure location permissions are enabled.
- Repeated calls will override previous callbacks.
# onBluetoothAdapterStateChange(function callback)
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Listens for changes in the Bluetooth adapter state.
Parameters
function callback
Callback function for the event when the Bluetooth adapter state changes.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| available | boolean | Whether the Bluetooth adapter is available |
| discovering | boolean | Whether the Bluetooth adapter is in the search state |
Note Repeated calls will override previous callbacks.
# offBluetoothDeviceFound
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Cancels listening for events when a new device is discovered.
# offBluetoothAdapterStateChange
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Cancels listening for changes in the Bluetooth adapter state.
# makeBluetoothPair(Object object)
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Bluetooth pairing interface, Android only.
In most cases (when a specific pin code or password needs to be provided), the system will take over the pairing process, and calling createBLEConnection directly is sufficient. This interface should only be used if the developer does not want the user to manually input the pin code and real-device verification confirms it works properly.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| deviceId | string | Yes | Bluetooth device ID | |
| pin | string | Yes | Pin code, in Base64 format. | |
| timeout | number | 20000 | No | Timeout duration, in ms |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed whether the call succeeds or fails) |
# getConnectedBluetoothDevices(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above support, dependent on Extension SDK
Obtain connected Bluetooth devices based on the primary service UUID.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| services | Array.string | Yes | List of UUIDs for the primary service of the Bluetooth device (supports 16/32/128-bit UUID) | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when the API call ends (executed whether the call succeeds or fails) |
object.success callback function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| devices | Array.Object | List of discovered devices |
Structure of res.devices
| Property | Type | Description |
|---|---|---|
| name | string | Name of the Bluetooth device; some devices may not have one |
| deviceId | string | ID used to distinguish the device |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| -1 | already connected | Already connected |
| 10000 | not init | Bluetooth adapter not initialized |
| 10001 | not available | Current Bluetooth adapter is unavailable |
| 10002 | no device | Specified device not found |
| 10003 | connection fail | Connection failed |
| 10004 | no service | Specified service not found |
| 10005 | no characteristic | Specified characteristic not found |
| 10006 | no connection | Current connection has been disconnected |
| 10007 | property not support | Current characteristic does not support this operation |
| 10008 | system error | All other exceptions reported by the system |
| 10009 | system not support | Android-specific; BLE not supported on systems below version 4.3 |
| 10012 | operate time out | Connection timeout |
| 10013 | invalid_data | Connection deviceId is empty or incorrectly formatted |
# getBluetoothDevices(Object object)
Retrieve all Bluetooth devices discovered during the active period of the Bluetooth module, including devices currently connected to this device.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when the API call ends (executed whether the call succeeds or fails) |
object.success callback function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| devices | Array.Object | List of connected devices corresponding to the UUID |
Structure of res.devices
| Property | Type | Description |
|---|---|---|
| name | string | Name of the Bluetooth device; some devices may not have one |
| deviceId | string | ID of the Bluetooth device |
| RSSI | number | Signal strength of the current Bluetooth device, in dBm |
| advertisData | ArrayBuffer | ManufacturerData segment from the broadcast data section of the current Bluetooth device |
| advertisServiceUUIDs | Array.string | ServiceUUIDs segment from the broadcast data section of the current Bluetooth device |
| localName | string | LocalName segment from the broadcast data section of the current Bluetooth device |
| serviceData | Object | ServiceData segment from the broadcast data section of the current Bluetooth device |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| -1 | already connected | Already connected |
| 10000 | not init | Bluetooth adapter not initialized |
| 10001 | not available | Current Bluetooth adapter is unavailable |
| 10002 | no device | Specified device not found |
| 10003 | connection fail | Connection failed |
| 10004 | no service | Specified service not found |
| 10005 | no characteristic | Specified characteristic not found |
| 10006 | no connection | Current connection has been disconnected |
| 10007 | property not support | Current characteristic does not support this operation |
| 10008 | system error | All other exceptions reported by the system |
| 10009 | system not support | Android-specific; BLE not supported on systems below version 4.3 |
| 10012 | operate time out | Connection timeout |
| 10013 | invalid_data | Connection deviceId is empty or incorrectly formatted |
# getBluetoothAdapterState(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above support, dependent on Extension SDK
Retrieve the status of the local Bluetooth adapter.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when the API call ends (executed whether the call succeeds or fails) |
object.success callback function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| discovering | boolean | Whether the device is currently searching |
| available | boolean | Whether the Bluetooth adapter is available |
# closeBluetoothAdapter(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above support, dependent on Extension SDK
Close the Bluetooth module. Calling this method will disconnect all established connections and release system resources. It is recommended to use this method in conjunction with openBluetoothAdapter after completing the Bluetooth process.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when the API call ends (executed whether the call succeeds or fails) |
# Bluetooth - Low Energy Central Device
# writeBLECharacteristicValue(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above support, dependent on Extension SDK
Write binary data to the characteristic value of a Bluetooth Low Energy (BLE) device. Note: The device's characteristic must support write operations for this to succeed.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| deviceId | string | Yes | ID of the Bluetooth device | |
| serviceId | string | Yes | UUID of the service corresponding to the Bluetooth characteristic | |
| characteristicId | string | Yes | UUID of the Bluetooth characteristic | |
| value | ArrayBuffer | Yes | Binary value corresponding to the Bluetooth device characteristic | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when the API call ends (executed whether the call succeeds or fails) |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| -1 | already connected | Already connected |
| 10000 | not init | Bluetooth adapter not initialized |
| 10001 | not available | Current Bluetooth adapter is unavailable |
| 10002 | no device | Specified device not found |
| 10003 | connection fail | Connection failed |
| 10004 | no service | Specified service not found |
| 10005 | no characteristic | Specified characteristic not found |
| 10006 | no connection | Current connection has been disconnected |
| 10007 | property not support | Current characteristic does not support this operation |
| 10008 | system error | All other exceptions reported by the system |
| 10009 | system not support | Android-specific; BLE not supported on systems below version 4.3 |
| 10012 | operate time out | Connection timeout |
| 10013 | invalid_data | Connection deviceId is empty or incorrectly formatted |
# setBLEMTU(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above support, dependent on Extension SDK
Negotiate and set the Maximum Transmission Unit (MTU) for Bluetooth Low Energy (BLE). This must be called after createBLEConnection is successfully invoked. Only effective on Android systems version 5.1 and above; iOS does not support due to system limitations.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| deviceId | string | Yes | ID of the Bluetooth device | |
| mtu | number | Yes | Maximum Transmission Unit. Range is between (22, 512), in bytes | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when the API call ends (executed whether the call succeeds or fails) |
object.success callback function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| mtu | number | Final negotiated MTU value, consistent with the input parameter. Supported starting from Android client 8.0.9 |
object.fail callback function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| mtu | number | Final negotiated MTU value. If negotiation fails, this parameter will not be present. Supported starting from Android client 8.0.9 |
# readBLECharacteristicValue(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above support, dependent on Extension SDK
Read binary data from the characteristic value of a Bluetooth Low Energy (BLE) device. Note: The device's characteristic must support read operations for this to succeed.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| deviceId | string | Yes | ID of the Bluetooth device | |
| serviceId | string | Yes | UUID of the service corresponding to the Bluetooth characteristic | |
| characteristicId | string | Yes | UUID of the Bluetooth characteristic | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when the API call ends (executed whether the call succeeds or fails) |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| -1 | already connected | Already connected |
| 10000 | not init | Bluetooth adapter not initialized |
| 10001 | not available | Current Bluetooth adapter is unavailable |
| 10002 | no device | Specified device not found |
| 10003 | connection fail | Connection failed |
| 10004 | no service | Specified service not found |
| 10005 | no characteristic | Specified characteristic not found |
| 10006 | no connection | Current connection has been disconnected |
| 10007 | property not support | Current characteristic does not support this operation |
| 10008 | system error | All other exceptions reported by the system |
| 10009 | system not support | Android-specific; BLE not supported on systems below version 4.3 |
| 10012 | operate time out | Connection timeout |
| 10013 | invalid_data | Connection deviceId is empty or incorrectly formatted |
Notes
- Concurrent calls may result in read failures.
- Information retrieved by the interface needs to be obtained through the callback registered in the onBLECharacteristicValueChange method.
# onBLEConnectionStateChange(function callback)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, depends on Extension SDK
Listens for changes in the Bluetooth Low Energy (BLE) connection state. This includes events such as developers actively connecting or disconnecting, device loss, abnormal disconnection, etc.
Parameters
function callback
Callback function for changes in the BLE connection state.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| deviceId | string | Bluetooth device ID |
| connected | boolean | Whether it is currently in a connected state |
Note
Repeated calls will override the original callback.
# onBLECharacteristicValueChange(function callback)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, depends on Extension SDK
Listens for characteristic value change events of Bluetooth Low Energy devices. The notifyBLECharacteristicValueChange interface must be called first to receive device notifications.
Parameters
function callback
Callback function for characteristic value change events of Bluetooth Low Energy devices.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| deviceId | string | Bluetooth device ID |
| serviceId | string | UUID of the service corresponding to the Bluetooth characteristic |
| characteristicId | string | UUID of the Bluetooth characteristic |
| value | ArrayBuffer | Latest value of the characteristic |
Note
Repeated calls will override the original callback.
# offBLEConnectionStateChange
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, depends on Extension SDK
Cancels listening for changes in the BLE connection state.
# offBLECharacteristicValueChange
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, depends on Extension SDK
Cancels listening for characteristic value change events of Bluetooth Low Energy devices.
# notifyBLECharacteristicValueChange(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, depends on Extension SDK
Enables the notify function for characteristic value changes in Bluetooth Low Energy devices, subscribing to characteristics. Note: The device's characteristic must support notify or indicate for this call to succeed.
Additionally, notifyBLECharacteristicValueChange must be enabled first to listen for the characteristicValueChange event.
Parameters
Object res
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| deviceId | string | Yes | Bluetooth device ID | |
| serviceId | string | Yes | UUID of the service corresponding to the Bluetooth characteristic | |
| characteristicId | string | Yes | UUID of the Bluetooth characteristic | |
| state | boolean | Yes | Whether to enable notify | |
| type | string | indication | No | Sets the characteristic subscription type; valid values are notification and indication |
| success | function | No | Callback function for successful interface invocation | |
| fail | function | No | Callback function for failed interface invocation | |
| complete | function | No | Callback function for when the interface invocation ends (executed whether the call succeeds or fails) |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| -1 | already connected | Already connected |
| 10000 | not init | Bluetooth adapter not initialized |
| 10001 | not available | Current Bluetooth adapter unavailable |
| 10002 | no device | Specified device not found |
| 10003 | connection fail | Connection failed |
| 10004 | no service | Specified service not found |
| 10005 | no characteristic | Specified characteristic not found |
| 10006 | no connection | Current connection has been disconnected |
| 10007 | property not support | Current characteristic does not support this operation |
| 10008 | system error | All other system-reported exceptions |
| 10009 | system not support | Android-specific; system versions below 4.3 do not support BLE |
| 10012 | operate time out | Connection timeout |
| 10013 | invalid_data | Connection deviceId is empty or incorrectly formatted |
Note
After a successful subscription operation, the device needs to actively update the characteristic's value to trigger the onBLECharacteristicValueChange callback.
On the Android platform, immediately calling the writeBLECharacteristicValue interface after successfully invoking this interface may result in a 10008 system error on some models.
# getBLEDeviceServices(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, depends on Extension SDK
Retrieves all services (service) of a Bluetooth Low Energy device.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| deviceId | string | Yes | Bluetooth device ID. A connection must have been established via createBLEConnection. | |
| success | function | No | Callback function for successful interface invocation | |
| fail | function | No | Callback function for failed interface invocation | |
| complete | function | No | Callback function for when the interface invocation ends (executed whether the call succeeds or fails) |
# getBLEDeviceRSSI(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, depends on Extension SDK
Retrieves the Received Signal Strength Indication (RSSI) of a Bluetooth Low Energy device.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| deviceId | string | Yes | Bluetooth device ID | |
| success | function | No | Callback function for successful interface invocation | |
| fail | function | No | Callback function for failed interface invocation | |
| complete | function | No | Callback function for when the interface invocation ends (executed whether the call succeeds or fails) |
object.success Callback Function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| RSSI | Number | Signal strength, in dBm |
# getBLEDeviceCharacteristics(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, depends on Extension SDK
Retrieves all characteristics (characteristic) of a specific service of a Bluetooth Low Energy device.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| deviceId | string | Yes | Bluetooth device ID. A connection must have been established via createBLEConnection. | |
| serviceId | string | Yes | Bluetooth service UUID. Must first call getBLEDeviceServices to retrieve. | |
| success | function | No | Callback function for successful interface invocation | |
| fail | function | No | Callback function for failed interface invocation | |
| complete | function | No | Callback function for when the interface invocation ends (executed whether the call succeeds or fails) |
# createBLEConnection(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, depends on Extension SDK
Connects to a Bluetooth Low Energy device.
If the Mini-Program has previously searched for a Bluetooth device and successfully established a connection, you can directly pass the previously obtained deviceId to attempt a connection without performing another search.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| deviceId | string | Yes | Bluetooth device ID | |
| timeout | number | No | Timeout duration in ms; if not provided, there will be no timeout | |
| success | function | No | Callback function for successful interface invocation | |
| fail | function | No | Callback function for failed interface invocation | |
| complete | function | No | Callback function for when the interface invocation ends (executed whether the call succeeds or fails) |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| -1 | already connected | Already connected |
| 10000 | not init | Bluetooth adapter not initialized |
| 10001 | not available | Current Bluetooth adapter unavailable |
| 10002 | no device | Specified device not found |
| 10003 | connection fail | Connection failed |
| 10004 | no service | Specified service not found |
| 10005 | no characteristic | Specified characteristic not found |
| 10006 | no connection | Current connection has been disconnected |
| 10007 | property not support | Current characteristic does not support this operation |
| 10008 | system error | All other system-reported exceptions |
| 10009 | system not support | Android-specific; system versions below 4.3 do not support BLE |
| 10012 | operate time out | Connection timeout |
| 10013 | invalid_data | Connection deviceId is empty or incorrectly formatted |
Note
Ensure that createBLEConnection and closeBLEConnection interfaces are called in pairs as much as possible. On Android, repeatedly calling createBLEConnection to create connections may lead to the system holding multiple connection instances of the same device, causing closeBLEConnection to not actually disconnect from the device.
Bluetooth connections can be disconnected at any time. It is recommended to monitor the onBLEConnectionStateChange callback event and perform reconnection operations as needed when the Bluetooth device disconnects.
If data read/write operation interfaces are called on unconnected or disconnected devices, a 10006 error will be returned, suggesting a reconnection operation.
# closeBLEConnection(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, depends on Extension SDK
Disconnects from a Bluetooth Low Energy device.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| deviceId | string | Yes | Bluetooth device ID | |
| success | function | No | Callback function for successful interface invocation | |
| fail | function | No | Callback function for failed interface invocation | |
| complete | function | No | Callback function for when the interface invocation ends (executed whether the call succeeds or fails) |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| -1 | already connected | Already connected |
| 10000 | not init | Bluetooth adapter not initialized |
| 10001 | not available | Current Bluetooth adapter unavailable |
| 10002 | no device | Specified device not found |
| 10003 | connection fail | Connection failed |
| 10004 | no service | Specified service not found |
| 10005 | no characteristic | Specified characteristic not found |
| 10006 | no connection | Current connection has been disconnected |
| 10007 | property not support | Current characteristic does not support this operation |
| 10008 | system error | All other system-reported exceptions |
| 10009 | system not support | Android-specific; system versions below 4.3 do not support BLE |
| 10012 | operate time out | Connection timeout |
| 10013 | invalid_data | Connection deviceId is empty or incorrectly formatted |
# Bluetooth - Low Energy Peripheral Devices
# onBLEPeripheralConnectionStateChanged(function callback)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, requires Extension SDK
Listens for the event when the current peripheral device is connected or disconnected.
Parameters
Object object
Callback function for the event when the current peripheral device is connected or disconnected.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| deviceId | String | ID of the device whose connection status has changed |
| serverId | String | UUID of the server |
| connected | Boolean | Current connection status |
# offBLEPeripheralConnectionStateChanged
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, requires Extension SDK
Cancels listening for the event when the current peripheral device is connected or disconnected.
# createBLEPeripheralServer(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, requires Extension SDK
Creates a local service as a Bluetooth Low Energy (BLE) peripheral server. Multiple servers can be created.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed regardless of success or failure) |
object.success Callback Function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| server | BLEPeripheralServer | Peripheral server. |
# BLEPeripheralServer.addService(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, requires Extension SDK
Adds a service.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| service | Object | Yes | Object describing the service | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed regardless of success or failure) |
Structure of object.service
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| uuid | String | Yes | UUID of the Bluetooth service | |
| characteristics | Array.Object | Yes | List of characteristics |
Structure of characteristics
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| uuid | String | Yes | UUID of the characteristic | |
| properties | Object | No | Supported operations of the characteristic | |
| permission | Object | No | Permissions of the characteristic | |
| value | ArrayBuffer | No | Binary value corresponding to the characteristic | |
| descriptors | Array.Object | No | Descriptor data |
Structure of properties
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| write | Boolean | false | No | Write |
| writeNoResponse | Boolean | false | No | Write without response |
| read | Boolean | false | No | Read |
| notify | Boolean | false | No | Subscribe |
| indicate | Boolean | false | No | Acknowledgment |
Structure of permission
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| readable | Boolean | false | No | Readable |
| writeable | Boolean | false | No | Writable |
| readEncryptionRequired | Boolean | false | No | Encrypted read request |
| writeEncryptionRequired | Boolean | false | No | Encrypted write request |
Structure of descriptors
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| uuid | String | Yes | UUID of the Descriptor | |
| permission | Object | No | Permissions of the descriptor | |
| value | ArrayBuffer | No | Descriptor data |
Structure of permission
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| write | Boolean | false | No | Write |
| read | Boolean | false | No | Read |
# BLEPeripheralServer.close(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, requires Extension SDK
Closes the current server.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for when the API call ends (executed regardless of success or failure) |
# BLEPeripheralServer.offCharacteristicReadRequest()
Cancels listening for the event where a connected device requests to read the characteristic value of the current peripheral device.
# BLEPeripheralServer.offCharacteristicSubscribed()
Cancels listening for characteristic subscription events.
# BLEPeripheralServer.offCharacteristicUnsubscribed()
Cancels listening for characteristic unsubscription events.
# BLEPeripheralServer.offCharacteristicWriteRequest()
Cancels listening for the event where a connected device requests to write the characteristic value of the current peripheral device.
# BLEPeripheralServer.onCharacteristicReadRequest(function callback)
Parameters
function callback
Callback function for the event where a connected device requests to read the characteristic value of the current peripheral device.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| serviceId | String | UUID of the service corresponding to the Bluetooth characteristic |
| characteristicId | String | UUID of the Bluetooth characteristic |
| callbackId | Number | Unique identifier, used when calling writeCharacteristicValue |
Note Repeated calls will overwrite the previous callback.
# BLEPeripheralServer.onCharacteristicSubscribed(function callback)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, requires Extension SDK
Listens for characteristic subscription events, only supported on iOS.
Parameters
function callback
Callback function for characteristic subscription events.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| serviceId | String | UUID of the service corresponding to the Bluetooth characteristic |
| characteristicId | String | UUID of the Bluetooth characteristic |
Note Repeated calls will overwrite the previous callback.
# BLEPeripheralServer.onCharacteristicUnsubscribed(function callback)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, requires Extension SDK
Listens for characteristic unsubscription events, only supported on iOS.
Parameters
function callback
Callback function for characteristic unsubscription events.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| serviceId | String | UUID of the service corresponding to the Bluetooth characteristic |
| characteristicId | String | UUID of the Bluetooth characteristic |
Note Repeated calls will overwrite the previous callback.
# BLEPeripheralServer.onCharacteristicWriteRequest(function callback)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, requires Extension SDK
Listens for the event where a connected device requests to write the characteristic value of the current peripheral device. After receiving this message, you need to immediately call writeCharacteristicValue to write back the data; otherwise, the host will not receive a response.
Parameters
function callback
Callback function for the event where a connected device requests to write the characteristic value of the current peripheral device.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| serviceId | String | UUID of the service corresponding to the Bluetooth characteristic |
| characteristicId | String | UUID of the Bluetooth characteristic |
Note Repeated calls will overwrite the previous callback.
# BLEPeripheralServer.removeService(Object object)
Base Library 2.11.2 and above, iOS SDK 2.34.1 and above, Android SDK 2.34.1 and above supported, requires Extension SDK
Removes a service. Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| serviceId | String | Yes | UUID of the service | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when API call ends (executed whether successful or failed) |
# BLEPeripheralServer.startAdvertising(Object Object)
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Start broadcasting the locally created peripheral device.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| advertiseRequest | Object | Yes | Custom parameters for broadcasting | |
| powerLevel | String | medium | No | Broadcast power level |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when API call ends (executed whether successful or failed) |
Structure of Object.advertiseRequest
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| connectable | Boolean | true | No | Whether the current device is connectable |
| deviceName | String | No | The deviceName field in the broadcast, default is empty | |
| serviceUuids | Array.String | No | List of service UUIDs to broadcast. Refer to notes when using 16/32-bit UUIDs. | |
| manufacturerData | Array.Object | No | Manufacturer information for broadcasting. Only supported on Android; iOS cannot customize due to system restrictions. |
Structure of manufacturerData
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| manufacturerId | String | Yes | Manufacturer ID, hexadecimal starting with 0x | |
| manufacturerSpecificData | ArrayBuffer | No | Manufacturer-specific data |
Valid values for Object.powerLevel
| Value | Description | Minimum Version |
|---|---|---|
| low | Low power | |
| medium | Medium power | |
| high | High power |
Notes
- Starting from Android 8.0.9, direct use of 16/32/128-bit UUIDs is supported.
- Below Android 8.0.9, only 128-bit UUIDs are supported. When using 16/32-bit UUIDs, padding is required (the system will automatically identify if it belongs to a pre-allocated range).
- On iOS, 16-bit UUIDs must be used directly without padding to 128 bits; otherwise, the system will still transmit as 128 bits. iOS does not currently support 32-bit UUIDs.
- iOS can initiate only one advertisement at a time, while Android supports multiple simultaneous advertisements.
# BLEPeripheralServer.stopAdvertising(Object object)
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Stop broadcasting.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when API call ends (executed whether successful or failed) |
# BLEPeripheralServer.writeCharacteristicValue(Object Object)
Supported from Base Library 2.11.2, iOS SDK 2.34.1, Android SDK 2.34.1 onwards, depends on Extension SDK
Write binary data value to the specified characteristic and notify the connected host that the peripheral's characteristic value has changed. This interface handles whether to send a response or trigger a subscription.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| serviceId | String | Yes | UUID of the service corresponding to the Bluetooth characteristic | |
| characteristicId | String | Yes | UUID of the Bluetooth characteristic | |
| value | ArrayBuffer | Yes | Binary value corresponding to the characteristic | |
| needNotify | Boolean | Yes | Whether to notify the host that the value has been updated | |
| callbackId | Number | No | Optional, used for handling responses | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when API call ends (executed whether successful or failed) |
# Bluetooth - Beacon
# stopBeaconDiscovery(Object object)
Supported from Base Library 2.11.2, iOS version 2.34.1, depends on Extension SDK. Android does not currently support Beacon-related interfaces.
Stop searching for nearby Beacon devices.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when API call ends (executed whether successful or failed) |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| 11000 | unsupport | System or device does not support |
| 11001 | bluetooth service unavailable | Bluetooth service unavailable |
| 11002 | location service unavailable | Location service unavailable |
| 11003 | already start | Search already started |
| 11004 | not startBeaconDiscovery | Search not yet started |
| 11005 | system error | System error |
| 11006 | invalid data | Incorrect parameters |
# startBeaconDiscovery(Object object)
Supported from Base Library 2.11.2, iOS version 2.34.1, depends on Extension SDK. Android does not currently support Beacon-related interfaces.
Start searching for nearby Beacon devices.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| uuids | Array. | Yes | List of UUIDs broadcast by Beacon devices | |
| ignoreBluetoothAvailable | boolean | false | No | Whether to check Bluetooth status, valid only on iOS. Starting from iOS 11, even if Bluetooth is turned off in the control panel, Beacon services can still be used. |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when API call ends (executed whether successful or failed) |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| 11000 | unsupport | System or device does not support |
| 11001 | bluetooth service unavailable | Bluetooth service unavailable |
| 11002 | location service unavailable | Location service unavailable |
| 11003 | already start | Search already started |
| 11004 | not startBeaconDiscovery | Search not yet started |
| 11005 | system error | System error |
| 11006 | invalid data | Incorrect parameters |
Note
- Interface authorization failure (iOS):
- If the Host-App prohibits Mini-Programs from actively requesting permissions, an error message will be returned: unauthorized disableauthorized, indicating that the SDK is prohibited from requesting Bluetooth permissions.
# onBeaconUpdate(function callback)
Supported from Base Library 2.11.2, iOS version 2.34.1, depends on Extension SDK. Android does not currently support Beacon-related interfaces.
Listen for Beacon device update events. Only one listener can be registered.
Parameters
function callback
Callback function for Beacon device update events.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| beacons | Array.BeaconInfo | List of all currently discovered Beacon devices |
# onBeaconServiceChange(function callback)
Supported from Base Library 2.11.2, iOS version 2.34.1, depends on Extension SDK. Android does not currently support Beacon-related interfaces.
Listen for Beacon service status change events. Only one listener can be registered.
Parameters
function callback
Callback function for Beacon service status change events.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| available | boolean | Whether the service is currently available |
| discovering | boolean | Whether currently in search mode |
# offBeaconUpdate
Supported from Base Library 2.11.2, iOS version 2.34.1, depends on Extension SDK. Android does not currently support Beacon-related interfaces.
Cancel listening for Beacon device update events.
# offBeaconServiceChange
Supported from Base Library 2.11.2, iOS version 2.34.1, depends on Extension SDK. Android does not currently support Beacon-related interfaces.
Cancel listening for Beacon service status change events.
# getBeacons(Object object)
Supported from Base Library 2.11.2, iOS version 2.34.1, depends on Extension SDK. Android does not currently support Beacon-related interfaces.
Get all discovered Beacon devices.
Parameters
Object object
Callback function for Beacon service status change events.
Parameters
Object res
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when API call ends (executed whether successful or failed) |
object.success callback function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| beacons | Array.BeaconInfo | List of Beacon devices |
Errors
| Error Code | Error Message | Description |
|---|---|---|
| 0 | ok | Normal |
| 11000 | unsupport | System or device does not support |
| 11001 | bluetooth service unavailable | Bluetooth service unavailable |
| 11002 | location service unavailable | Location service unavailable |
| 11003 | already start | Search already started |
| 11004 | not startBeaconDiscovery | Search not yet started |
| 11005 | system error | System error |
| 11006 | invalid data | Incorrect parameters |
# BeaconInfo
Beacon device.
Properties
string uuid
UUID broadcast by the Beacon device.
number major
Primary ID of the Beacon device.
number minor
Secondary ID of the Beacon device.
number proximity
Enumeration value representing the distance of the device (iOS only).
Valid values for proximity
| Value | Description | Minimum Version |
|---|---|---|
| 0 | Signal too weak to calculate distance, or non-iOS device | |
| 1 | Very close | |
| 2 | Relatively close | |
| 3 | Far |
number accuracy
Distance to the Beacon device, in meters. On iOS, when proximity is 0, accuracy is -1.
number rssi
Signal strength of the device, in dBm.
# Accessibility
# checkIsOpenAccessibility
Supported from Base Library 2.12.1 onwards.
checkIsOpenAccessibility(Object object)
Check whether visual accessibility features are enabled.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function when API call ends (executed whether successful or failed) |
object.success callback function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| open | Boolean | Returns true if VoiceOver is enabled on iOS or TalkBack is enabled on Android. |