# Basics

# System

# getSystemInfoSync

getSystemInfoSync()

Synchronous version of getSystemInfo.

# getSystemInfoAsync

ft.getSystemInfoAsync(Object object)

Asynchronously obtain system information.

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 on both success and failure)

object.success callback function

Parameters

Object res

Property Type Description Minimum Version
brand string Device brand 1.5.0
model string Device model. New models may display as unknown for a period until adapted.
pixelRatio number Device pixel ratio
screenWidth number Screen width, in px 1.1.0
screenHeight number Screen height, in px 1.1.0
windowWidth number Usable window width, in px
windowHeight number Usable window height, in px
statusBarHeight number Status bar height, in px 1.9.0
language string APP set language
version string Version number
system string Operating system and version
platform string Client platform
fontSizeSetting number User font size (in px) 1.5.0
SDKVersion string Client Base Library version 1.1.0
benchmarkLevel number Device performance level (Android only). Values: -2 or 0 (device cannot run mini-games), -1 (performance unknown), >=1 (device performance value, higher means better performance, currently less than 50) 1.8.0
albumAuthorized boolean Switch for allowing use of photo album (iOS only) 2.6.0
cameraAuthorized boolean Switch for allowing use of camera 2.6.0
locationAuthorized boolean Switch for allowing use of location 2.6.0
microphoneAuthorized boolean Switch for allowing use of microphone 2.6.0
notificationAuthorized boolean Switch for allowing notifications 2.6.0
notificationAlertAuthorized boolean Switch for allowing notifications with alerts (iOS only) 2.6.0
notificationBadgeAuthorized boolean Switch for allowing notifications with badges (iOS only) 2.6.0
notificationSoundAuthorized boolean Switch for allowing notifications with sound (iOS only) 2.6.0
bluetoothEnabled boolean Bluetooth system switch 2.6.0
locationEnabled boolean Geolocation system switch 2.6.0
wifiEnabled boolean Wi-Fi system switch 2.6.0
safeArea Object Safe area in portrait orientation 2.7.0
locationReducedAccuracy boolean true indicates fuzzy positioning, false indicates precise positioning, iOS only
theme string Current system theme, values: light or dark, only accessible if global configuration "darkmode":true, otherwise undefined (not supported in mini-games) 2.11.0
enableDebug boolean Whether debugging is enabled. Can be toggled via top-right menu or ft.setEnableDebug. 2.15.0
deviceOrientation string Device orientation

safeArea structure

Property Type Description
left number X-coordinate of the top-left corner of the safe area
right number X-coordinate of the bottom-right corner of the safe area
top number Y-coordinate of the top-left corner of the safe area
bottom number Y-coordinate of the bottom-right corner of the safe area
width number Width of the safe area, in logical pixels
height number Height of the safe area, in logical pixels

Valid values for theme

Value Description Minimum Version
dark Dark theme
light Light theme

host structure

Property Type Description
appId string AppId corresponding to the Host-App

Valid values for deviceOrientation

Value Description Minimum Version
portrait Portrait
landscape Landscape

Sample Code

Preview the effect in the Developer Tools

ft.getSystemInfoAsync({
  success (res) {
    console.log(res.model)
    console.log(res.pixelRatio)
    console.log(res.windowWidth)
    console.log(res.windowHeight)
    console.log(res.language)
    console.log(res.version)
    console.log(res.platform)
  }
})

# getSystemInfo

getSystemInfo(Object object)

Get system information.

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 on both success and failure)

object.success callback function ​ Parameters

Object res

Property Type Description
SDKVersion string Mini-Program Base Library version number
runtimeSDKVersion string Mini-Program SDK version number
brand string Device brand
model string Device model
pixelRatio number Device pixel ratio
screenWidth number Screen width, in px
screenHeight number Screen height, in px
windowWidth number Usable window width, in px
windowHeight number Usable window height, in px
statusBarHeight number Status bar height, in px
language string Host-App set language
version string Host-App version number
system string Operating system and version
platform string Client platform
inFinChat boolean Whether in FinChat Mini-Program environment
deviceId string Device identifier

Sample Code

 ft.getSystemInfo({
  success(res) {
    console.log(res.model)
    console.log(res.pixelRatio)
    console.log(res.windowWidth)
    console.log(res.windowHeight)
    console.log(res.language)
    console.log(res.version)
    console.log(res.platform)
  }
})

# Updates

# getUpdateManager

Get the globally unique version update manager to manage Mini-Program updates. Returns UpdateManager.

UpdateManager Methods

UpdateManager.applyUpdate() Forces the Mini-Program to restart and use the new version. Called after the new version of the Mini-Program has been downloaded (i.e., after receiving the onUpdateReady callback).

UpdateManager.onCheckForUpdate(function callback) Listens for events that check for updates from the backend. The SDK automatically checks for updates when the Mini-Program cold starts; no need for developers to trigger it actively.

UpdateManager.onUpdateReady(function callback) Listens for events indicating that a new version of the Mini-Program is available. The client triggers the download automatically (no developer action required); the callback is executed after the download succeeds.

UpdateManager.onUpdateFailed(function callback) Listens for events indicating that a Mini-Program update has failed. If a new version of the Mini-Program is available, the client triggers the download automatically (no developer action required); the callback is executed after the download fails (possibly due to network issues, etc.).

Sample Code

const updateManager = ft.getUpdateManager()

updateManager.onCheckForUpdate(function (res) {
  // Callback after requesting new version information
  console.log(res.hasUpdate)
})

updateManager.onUpdateReady(function () {
  ft.showModal({
    title: 'Update Prompt',
    content: 'The new version is ready. Restart the application?',
    success: function (res) {
      if (res.confirm) {
        // The new version has been downloaded. Call applyUpdate to apply the new version and restart.
        updateManager.applyUpdate()
      }
    }
  })
})

updateManager.onUpdateFailed(function () {
  // New version download failed
})

# Mini-Games

# onShow

ft.onShow(function callback)

Listens for the event when the Mini-Game comes to the foreground.

Parameters

function callback

Callback function for when the Mini-Game comes to the foreground.

Parameters

Object res

Property Type Description
path string Path when the Mini-Game comes to the foreground (code package path)
query Object Query parameters when the Mini-Program comes to the foreground
referrerInfo Object Referrer information. Returned when entering from another Mini-Program, Official Account, or App. Otherwise, returns {}. (See note below)

referrerInfo structure

Property Type Description
appId string AppId of the Mini-Program
extraData Object Data passed from the source Mini-Program

Note

In some versions, referrerInfo may return undefined if absent. It is recommended to use options.referrerInfo && options.referrerInfo.appId for judgment.

# onHide

ft.onHide(function callback)

Listens for the event when the Mini-Game goes to the background.

Parameters

function callback

Callback function for when the Mini-Game goes to the background

# offShow

ft.offShow(function callback)

Unlisten to the Mini-Game coming to the foreground event.

Parameters

function callback

Callback function for the Mini-Game coming to the foreground event.

# offHide

ft.offHide(function callback)

Unlisten to the Mini-Game going to the background event.

Parameters

function callback

Callback function for the Mini-Game going to the background event.

# getLaunchOptionsSync

Object ft.getLaunchOptionsSync() Get the parameters when the Mini-Game starts.

Return Value

Object

Startup parameters

Property Type Description
query Object Query parameters when starting the Mini-Game
referrerInfo Object Referrer information

Structure of referrerInfo

Property Type Description
appId string AppId of the source Mini-Program, Official Account, or App
extraData Object Data passed from the source Mini-Program

# getEnterOptionsSync

Object ft.getEnterOptionsSync()

Get the parameters at the time of this Mini-Game startup. Return Value

Object

Startup parameters

Property Type Description
query Object Query parameters when starting the Mini-Game
referrerInfo Object Referrer information

Structure of referrerInfo

Property Type Description
appId string AppId of the Mini-Program
extraData Object Data passed from the source Mini-Program

Note

In some versions, undefined may be returned when there is no referrerInfo. It is recommended to use options.referrerInfo && options.referrerInfo.appId for judgment.

# Application-Level Events

# onError

ft.onError(function callback)

Listen to Mini-Game error events, such as script errors or API call errors.

Parameters

function callback

Callback function for Mini-Game error events

Parameters

string error

Error message, including stack trace

# onAudioInterruptionBegin

ft.onAudioInterruptionBegin(function callback)

Listen to the event when audio is interrupted due to system occupation. This event can be triggered in scenarios including but not limited to alarms, phone calls, etc.

After this event is triggered, all audio within the Mini-Program will pause.

Parameters

function callback

Listener function for the event when audio is interrupted due to system occupation

# onAudioInterruptionEnd

ft.onAudioInterruptionEnd(function callback)

Listen to the event when audio interruption ends.

After receiving the onAudioInterruptionEnd event, all audio within the Mini-Game will pause and can only be played again after receiving this event.

Parameters

function callback

Listener function for the event when audio interruption ends

# offError

ft.offError(function callback)

Unlisten to Mini-Game error events.

Parameters

function callback

Callback function passed into onError

# offAudioInterruptionBegin

ft.offAudioInterruptionBegin(function callback)

Unlisten to the event when audio is interrupted due to system occupation.

Parameters

function callback

Callback function passed into onAudioInterruptionBegin

# offAudioInterruptionEnd

ft.offAudioInterruptionEnd(function callback)

Unlisten to the event when audio interruption ends.

Parameters

function callback

Callback function passed into onAudioInterruptionEnd

# Debugging

# setEnableDebug

ft.setEnableDebug(Object object)

Set whether to turn on the debug switch. This switch can take effect even in the official version.

Parameters

Object object

Property Type Default Required Description
enableDebug boolean Yes Whether to turn on debugging
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for API call completion (executed regardless of success or failure)

Sample Code

// Turn on debugging
ft.setEnableDebug({
  enableDebug: true
})

// Turn off debugging
ft.setEnableDebug({
  enableDebug: false
})

Tips

  • Another way to turn on debugging in the official version is to first turn it on in the development or trial version, then switch to the official version to see vConsole.

# Others

# getAccountInfoSync

ft.getAccountInfoSync()

Function Description Get current account information. The online Mini-Program version number can only be obtained in the official version of the Mini-Program and cannot be obtained in the development or trial version.

Return Value

Object

Account information

Property Type Description
miniProgram Object Mini-Program account information

Sample Code

const accountInfo = ft.getAccountInfoSync()
console.log(accountInfo) // Mini-Program appId
© FinClip with ❤ , Since 2017