# 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: accuracy is 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: accuracy is 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):
  1. If the user denies authorization, it will return the error message: unauthorized, user did not grant camera permission
  2. 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):
  1. If the user denies authorization, it will return the error message: fail unauthorized user did not grant camera permission
  2. 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):
  1. If the user denies authorization, it will return the error message: unauthorized user did not grant vibration permission
  2. 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):
  1. If the user denies authorization, it will return the error message: unauthorized user did not grant vibration permission
  2. 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 openBluetoothAdapter will 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 via onBluetoothAdapterStateChange, or call all Bluetooth module APIs.

Note

  • Interface authorization failure (iOS):
  1. 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 onBluetoothDeviceFound callback, this device will be added to the array obtained by the getBluetoothDevices interface.
  • 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):
    1. 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.
© FinClip with ❤ , Since 2017