# 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(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(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.

iOS Calling Method

Android Calling Method

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)
© FinClip with ❤ , Since 2017