# H5 Application API
# General APIs
# onAppShow
ft.onAppShow(function callback)
Listens for the application switching to foreground event.
Parameters
function callback
Callback function for the application switching to foreground event.
Example Code
function show() {
console.log('on app show')
}
ft.onAppShow(show)
ft.offAppShow(show)
# onAppHide
ft.onAppHide(function callback)
Listens for the application switching to background event.
Parameters
function callback
Callback function for the application switching to background event.
Example Code
function hide() {
console.log('on app hide')
}
ft.onAppHide(hide)
ft.offAppHide(hide)
# offAppShow
ft.offAppShow(function callback)
Cancels listening for the application switching to foreground event.
Parameters
function callback
Callback function for the application switching to foreground event.
# offAppHide
ft.offAppHide(function callback)
Cancels listening for the application switching to background event.
Parameters
function callback
Callback function for the application switching to background event.
# navigateToMiniProgram
navigateToMiniProgram(Object object)
Opens another Mini-Program.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| appId | string | Yes | The appId of the Mini-Program to open | |
| path | string | No | The page path to open; opens the homepage if empty. The part after ? in the path becomes the query, which can be obtained in the App.onLaunch, App.onShow, and Page.onLoad callback functions of the Mini-Program, or in the ft.onShow callback function and ft.getLaunchOptionsSync of the Mini-Game. | |
| extraData | Object | No | Data to be passed to the target Mini-Program, which can be obtained in App.onLaunch and App.onShow of the target Mini-Program. If jumping to a Mini-Game, this data can be obtained in ft.onShow and ft.getLaunchOptionsSync. | |
| 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) |
Example
ft.navigateToMiniProgram({
appId: '',
.path: 'page/index/index?id=123',
extraData: {
foo: 'bar'
},
success(res) {
// Open successful
}
})
# navigateToWechatMiniProgram
navigateToWechatMiniProgram(Object object)
Jumps to open a WeChat Mini-Program.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| originId | string | Yes | Original ID | |
| path | string | No | The page path to open; opens the homepage if empty. The part after ? in the path becomes the query, which can be obtained in the App.onLaunch, App.onShow, and Page.onLoad callback functions of the Mini-Program, or in the ft.onShow callback function and ft.getLaunchOptionsSync of the Mini-Game. | |
| envVersion | String | release | No | The version of the Mini-Program to open. This parameter is only effective when the current Mini-Program is a development version or trial version. If the current Mini-Program is a release version, the opened Mini-Program will definitely be a release version. |
| 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) |
Valid Values for object.envVersion
| Value | Description | Minimum Version |
|---|---|---|
| develop | Development Version | |
| trial | Trial Version | |
| release | Release Version |
Example
ft.navigateToWechatMiniProgram({
originId: '',
.path: 'page/index/index?id=123'
})
# Custom APIs
# loadExtApi
loadExtApi(Object object)
Loads custom API configuration, equivalent to the configuration in FinClipConf.js.
For SDK-side configuration documentation, refer to:
iOS Custom API Configuration Documentation (opens new window)
Android Custom API Configuration Documentation (opens new window)
Parameters
Parameters for a single API item are as follows:
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Custom API name |
| sync | boolean | No | Whether it is a synchronous API |
| params | object | No | Parameter format; only required properties can be listed. If there are no restrictions, an empty object can be used directly. |
Example Code
ft.loadExtApi([
{
name: 'finclipLogin',
sync: false,
params: {
url: ''
}
},
{
name: 'finclipTestSync',
sync: true,
params: {
name:'',
title:''
}
}
])
// Asynchronous call example
ft.finclipLogin({
url: 'some url'
success: (res) => { console.log(res) },
fail: (res) => { console.log(res) },
})
// Synchronous call example
const res = ft.finclipTestSync({ name: '', title: ''})
console.log(res)
# Network
# request
request(Object object)
Initiates an HTTP network request using native APIs and returns a RequestTask object after execution.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| url | string | Yes | Developer server interface address | |
| data | string/object/ArrayBuffer | No | Request parameters | |
| header | Object | No | Sets the request header; Referer cannot be set in the header. content-type defaults to application/json | |
| method | string | GET | No | HTTP request method |
| timeout | number | No | Timeout period in milliseconds | |
| dataType | string | json | No | Return data format |
| responseType | string | text | No | Response data type |
| forceCellularNetwork | boolean | false | No | Use mobile network to send requests under WiFi (only supported on Android) |
| 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) |
Valid Values for object.method
| Value | Description |
|---|---|
| OPTIONS | HTTP request OPTIONS |
| GET | HTTP request GET |
| HEAD | HTTP request HEAD |
| POST | HTTP request POST |
| PUT | HTTP request PUT |
| DELETE | HTTP request DELETE |
| TRACE | HTTP request TRACE |
| CONNECT | HTTP request CONNECT |
Valid Values for object.dataType
| Value | Description |
|---|---|
| json | Returned data is JSON; JSON.parse will be performed on the returned data |
| Others | No JSON.parse will be performed on the returned content |
Valid Values for object.responseType
| Value | Description |
|---|---|
| text | Response data is text |
| arraybuffer | Response data is ArrayBuffer |
object.success Callback Function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| data | string/object/ArrayBuffer | Data returned by the developer server |
| statusCode | number | HTTP status code returned by the developer server |
| header | Object | HTTP Response Header returned by the developer server |
Example Code
ft.request({
url: 'test.php', // Example only, not a real interface address
data: {
x: '',
y: ''
},
header: {
'content-type': 'application/json' // Default value
},
success(res) {
console.log(res.data)
}
})
# RequestTask.abort
Supported from Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
RequestTask.abort()
Aborts the request task.
Example Code
const task = ft.request({
// some params
})
// Abort request
task.abort()
# RequestTask.onHeadersReceived
Supported from Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
RequestTask.onHeadersReceived(function callback)
Listens for the HTTP Response Header event, which occurs earlier than the request completion event.
Parameters
function callback
Callback function for the Header Received event.
Callback Function Parameters
Object res
| Property | Type | Description |
|---|---|---|
| header | Object | HTTP Response Header returned by the developer server |
# RequestTask.offHeadersReceived
Supported from Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
RequestTask.offHeadersReceived(function callback)
Cancels listening for the HTTP Response Header event.
Parameters
function callback
Callback function for the Header Received event.
# Data Cache
# setStorageSync
setStorageSync(string key, any data)
Synchronous version of ft.setStorage.
Parameters
string key
Specified key in the local cache.
any data
Content to be stored. Only supports native types, Date, and objects that can be serialized via JSON.stringify.
Example Code
ft.setStorage({
key: 'key',
data: 'value'
})
try {
ft.setStorageSync('key', 'value')
} catch (e) { }
# setStorage
setStorage(Object object)
Stores data in the specified key in the local cache, overwriting the original content corresponding to that key. The data storage lifecycle is consistent with the Mini-Program itself, meaning the data remains available unless actively deleted by the user or automatically cleaned up after a certain period. The total data storage limit is 10MB.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| key | string | Yes | Specified key in the local cache | |
| data | any | Yes | Content to be stored. Only supports native types, Date, and objects that can be serialized via JSON.stringify. | |
| 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) |
Example Code
ft.setStorage({
key: 'key',
data: 'value'
})
try {
ft.setStorageSync('key', 'value')
} catch (e) { }
# removeStorageSync
removeStorageSync(string key)
Synchronous version of ft.removeStorage.
Parameters
string key
Specified key in the local cache.
Example Code
ft.removeStorage({
key: 'key',
success(res) {
console.log(res)
}
})
try {
ft.removeStorageSync('key')
} catch (e) {
// Do something when catch error
}
# removeStorage
removeStorage(Object object)
Asynchronously removes the content corresponding to the specified key from the local cache.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| key | string | Yes | Specified key in the local cache | |
| 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) |
Example Code
ft.removeStorage({
key: 'key',
success(res) {
console.log(res)
}
})
try {
ft.removeStorageSync('key')
} catch (e) {
// Do something when catch error
}
# getStorageSync
getStorageSync(string key)
Synchronous version of ft.getStorage.
Parameters
string key
Specified key in the local cache.
Return Value
any
Local storage content corresponding to the key.
Example Code
ft.getStorage({
key: 'key',
success(res) {
console.log(res.data)
}
})
try {
const value = ft.getStorageSync('key')
if (value) {
// Do something with return value
}
} catch (e) {
// Do something when catch error
}
# getStorageInfoSync
getStorageInfoSync(Object object)
Synchronous version of ft.getStorageInfo.
Return Value
Object object
| Property | Type | Description |
|---|---|---|
| keys | Array.<string> | All keys in the current storage |
| currentSize | number | Current occupied space size, in KB |
| limitSize | number | Limited space size, in KB |
Example Code
ft.getStorageInfoSync({
success(res) {
console.log(res.keys)
console.log(res.currentSize)
console.log(res.limitSize)
}
})
try {
const res = ft.getStorageInfoSync()
console.log(res.keys)
console.log(res.currentSize)
console.log(res.limitSize)
} catch (e) {
// Do something when catch error
}
# getStorageInfo
getStorageInfo(Object object)
Gets relevant information about the current storage.
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 API call completion (executed regardless of success or failure) |
object.success Callback Function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| keys | Array.<string> | All keys in the current storage |
| currentSize | number | Current occupied space size, in KB |
| limitSize | number | Limited space size, in KB |
Example Code
ft.getStorageInfo({
success(res) {
console.log(res.keys)
console.log(res.currentSize)
console.log(res.limitSize)
}
})
try {
const res = ft.getStorageInfoSync()
console.log(res.keys)
console.log(res.currentSize)
console.log(res.limitSize)
} catch (e) {
// Do something when catch error
}
# getStorage
getStorage(Object object)
Gets the content corresponding to the specified key from the local cache.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| key | string | Yes | Specified key in the local cache | |
| 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) |
object.success Callback Function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| data | any | Content corresponding to the key |
Example Code
ft.getStorage({
key: 'key',
success(res) {
console.log(res.data)
}
})
try {
const value = ft.getStorageSync('key')
if (value) {
// Do something with return value
}
} catch (e) {
// Do something when catch error
}
# clearStorageSync
clearStorageSync(Object object)
Synchronous version of ft.clearStorage.
Example Code
ft.clearStorage()
try {
ft.clearStorageSync()
} catch (e) {
// Do something when catch error
}
# clearStorage
clearStorage(Object object)
Clears the local data cache.
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 API call completion (executed regardless of success or failure) |
Example Code
ft.clearStorage()
try {
ft.clearStorageSync()
} catch (e) {
// Do something when catch error
}
# Communication APIs
# onCustomEvent
onCustomEvent(callback)
Listens for the "onCustomEvent" event sent by the native side.
Example Code
const callback = (res) => {
console.log(res) // Gets parameters passed from the native side
}
ft.onCustomEvent(callback)
# offCustomEvent
offCustomEvent(callback)
Cancels listening for the onCustomEvent event. When callback is empty, clears all callbacks.
Example Code
const callback = (res) => {}
ft.onCustomEvent(callback)
// Clear specified callback
ft.offCustomEvent(callback)
// Clear all callbacks
ft.offCustomEvent()
# addCustomEventListener
addCustomEventListener(eventName, callback)
This event is a wrapper based on onCustomEvent, effectively reducing template code within onCustomEvent.
Note When using this event, to trigger normally, the data body when the SDK calls the event must have a name field indicating which eventName is triggered.
For example:
{
name: 'someMethod', // Required field
data: {
a: 'data-1',
b: 'data-2',
c: 1001
},
errMsg: 'some error msg'
}
The entire data will be passed through to the callback.
Example Code
const callback = (res) => {
console.log(res) // Gets parameters passed from the native side
}
ft.addCustomEventListener('someMethod', callback)
# removeCustomEventListener
removeCustomEventListener(eventName, callback)
Removes the listener added by addCustomEventListener.
Example Code
const callback = (res) => {
console.log(res) // Gets parameters passed from the native side
}
ft.removeCustomEventListener('someMethod', callback)