# 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:

  1. Registering custom APIs for use by native Mini-Programs;
  2. 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: extApi is 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);
© FinClip with ❤ , Since 2017