# API/Component Customization
# 1. Register Custom APIs
When a Mini-Program needs to call capabilities provided by the Host-App that are not implemented or cannot be implemented by the FinClip Mini-Program SDK, you can achieve this by registering custom APIs, enabling the Mini-Program to call APIs registered in the App.
Registering custom APIs is divided into two scenarios:
- Registering custom APIs for native Mini-Program use;
- Registering custom APIs for H5 pages loaded by the WebView component within the Mini-Program.
# 1.1 Register Asynchronous Mini-Program APIs
Function to register a custom API:
/**
* @params {string} name Custom API name
* @params {Function} handler Custom API implementation
**/
MopSDK.registerExtensionApi(name, handler);
For example, let's register a custom API named finclipLogin so it can be used directly within the Mini-Program.
First, after integrating the SDK into the App, register the custom API:
MopSDK.registerExtensionApi('finclipLogin', function (params) {
console.log(params);
// Implement the relevant return value logic
return {
errMsg: 'finclipLogin:ok',
data: '100',
};
});
Note
- The return value of a custom API should be of type map (contains key-value pairs).
- To trigger the fail callback, ensure
errMsgcontains'{command}:fail'; to trigger the success callback, ensureerrMsgcontains'{command}:ok'. Here,commandis the name of the custom API. - The return value should be serializable content.
Then, create a FinClipConf.js file in the root directory of the Mini-Program. Example configuration:
module.exports = {
extApi:[
{ // General interaction API
name: 'finclipLogin', // Extension API name. This API must be implemented by the Native side.
sync: false, // Whether it is a synchronous API
params: { // Parameter format for the extension API, only necessary properties can be listed
url: ''
}
}
]
}
Note:
extApiis an array, so you can register multiple custom APIs.
For more configuration information about custom APIs on the Mini-Program side, refer to ft.loadExtApi.
Finally, call the custom API within the Mini-Program. Example code:
ft.finclipLogin({
url:'https://www.baidu.com',
success: function (res) {
console.log("Calling customEvent success");
console.log(res);
},
fail: function (res) {
console.log("Calling customEvent fail");
console.log(res);
}
});
# 1.2 Register WebView Extension APIs
The Mini-Program can use the web-view component to load H5 pages. If the H5 page also needs to call a capability of the Host-App, you can register an API using this method.
const rnWebCustomAPI = params => {
console.warn('Webview custom API rnWebCustomAPI call', params);
return {
errMsg: 'rnWebCustomAPI:ok',
data: '100',
};
};
/**
* @params {String} name Custom API name
* @params {Function} handler Custom API implementation
**/
MopSDK.addWebExtentionApi('rnWebCustomAPI', rnWebCustomAPI);
Note
- The return value of a custom API should be of type map (contains key-value pairs).
- To trigger the fail callback, ensure
errMsgcontains'{command}:fail'; to return success, ensureerrMsgcontains'{command}:ok'. Here,commandis the name of the custom API. - The return value should be serializable content.
Reference our bridge JSSDK file within the H5 page, and then you can call the method registered above.
Example of calling the registered method within HTML:
window.ft.miniProgram.callNativeAPI('rnWebCustomAPI', {name:'xxxx'}, (result) => {
console.log(result)
});
# 2. RN Calls JS Methods in Webview
Similarly, if the Host-App wants to call a specific method within the H5 page loaded by the Mini-Program, it can use this API.
/**
* @param {string} appId
* @param {string} eventName Provided function name
* @param {Object} eventData Call parameters
**/
MopSDK.callJS(appId, 'app2jsFunction', {
data: 100
})
.then(res => {
console.warn('calljs call successful');
})
.catch(res => {
console.warn('calljs call failed');
});
First, reference our bridge JSSDK file within the H5 page.
Then, register the method within the HTML, for example, a method named app2jsFunction.
window.ft.onNativeAPIHandler('app2jsFunction', function(res) {
// app2jsFunction callback
})
Finally, the RN side calls the following API to invoke the JS function in the HTML:
var eventData = {result:'abc',code:'12345'};
MopSDK.callJS('Mini-Program ID', 'app2jsFunction', eventData);
# 3. RN Sends Global Messages to the Mini-Program
/**
* @param {String} appId
* @param {Object} eventData
**/
MopSDK.sendCustomEvent(appId,eventData)
Example code:
var eventData = {result:'abc',code:'12345'};
MopSDK.sendCustomEvent('Mini-Program ID', eventData);