# 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 use by native Mini-Programs;
- Registering custom APIs for use by H5 pages loaded via the WebView component within a Mini-Program.
# 1.1 Register Asynchronous Mini-Program APIs
Function to register a custom API:
/// register extension api
/// Register extension api
void registerExtensionApi(String name, ExtensionApiHandler 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:
Mop.instance.registerExtensionApi('finclipLogin', (params) async {
print("finclipLogin:$params");
return {};
});
Then, create a FinClipConf.js file in the root directory of the Mini-Program. The configuration example is as follows:
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 required properties can be listed
url: ''
}
}
]
}
Note:
extApiis an array, so you can register multiple custom APIs.
For more configuration information on the Mini-Program side for custom APIs, please 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 JS APIs
Mini-Programs can use the web-view component to load H5 pages. If the H5 page also wants to call a capability of the Host-App, you can use this method to register an API.
/// register webview extension api
/// Register webview extension api
void addWebExtentionApi(String name, ExtensionApiHandler handler)
Here, I register a method called js2AppFunction for H5 pages within the Mini-Program:
Mop.instance.addWebExtentionApi('js2AppFunction', (params) async {
print("js2AppFunction:$params");
return {};
});
Reference our bridge JSSDK file within the H5 page, and you can then call the method registered above.
Example of calling the registered method within HTML:
window.ft.miniProgram.callNativeAPI('js2AppFunction', {name:'getLocation'}, (result) => {
console.log(result)
});
# 2. Flutter Calling JS APIs
Similarly, if the Host-App wants to call a method within an H5 page loaded by the Mini-Program, you can use this API.
/// Native calls a js method in the webview
/// [appId] Mini-Program id
/// [eventName] Method name
/// [nativeViewId] webviewId
/// [eventData] Parameters
Future<void> callJS(String appId, String eventName, String nativeViewId,
Map<String, dynamic> eventData)
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, call the following API from the native side to invoke the JS function in the HTML:
Map<String, dynamic> eventData = {'result':'abc','code':'12345'};
Mop.instance.callJS('Mini-Program id', 'app2jsFunction', 'webviewId', eventData);
# 3. Native Sends Global Events to Mini-Program
/// Native sends an event to the Mini-Program
/// [appId] Mini-Program id
/// [eventData] Event object
Future<void> sendCustomEvent(
String appId, Map<String, dynamic> eventData)
Example code:
Map<String, dynamic> eventData = {'result':'abc','code':'12345'};
Mop.instance.sendCustomEvent('Mini-Program id', eventData);