# API/Component Customization

If 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, this can be achieved by registering custom APIs, allowing the Mini-Program to call APIs registered in the App.

Registering custom APIs covers two scenarios:

  1. Registering custom APIs for use by native Mini-Programs;
  2. Registering custom APIs for use by H5 pages loaded in the WebView component within a Mini-Program.

Please Note

Note: On the HarmonyOS platform, the above two scenarios are not specifically distinguished. Registered custom APIs can be used in both Mini-Programs and H5 pages loaded in the WebView component.

# 1. Custom Mini-Program API

Registering and using a custom Mini-Program API involves four steps:

  1. Implement the custom API
  2. Register the custom API
  3. Declare the custom API in the Mini-Program configuration
  4. Call the custom API within the Mini-Program

# 1.1 Registering a Custom Mini-Program Asynchronous API

# 1.1.1 Implementing a Custom Asynchronous API

Example of Implementing a Custom Mini-Program Asynchronous API

import { IApiManager } from "@finclip/sdk";

interface IFinClipLoginRes extends IApiManager.IInvokeBaseResponse {
  message: string
}

function finclipLogin(args: IApiManager.IInvokeArgs) {
  /**
   * params Parameters sent by the Mini-Program
   * callback Callback for success or failure
   */
  const params = args.params;
  const callback = args.callback;
  const extInfo = args.extInfo;
  console.log("finclipLogin params", JSON.stringify(params));
  // do something
  const res = true;
  // do something end
  if (res) {
    const res: IFinClipLoginRes = {
      message: "finclipLogin success !!"
    }
    callback.onSuccess(res);
  } else {
    callback.onFail({ errMsg: "finclipLogin fail !!" });
  }
}

# 1.1.2 Registering a Custom Asynchronous API

# 1.1.2.1 Global Registration
const instance = FinAppClient.getInstance();
instance?.registerCustomApi("finclipLogin", finclipLogin);
# 1.1.2.2 Individual Registration
async function startApplet() {
  const result = await client.startApplet({
    appId: "Mini-Program's appId",
    apiServer: "Server address",
  });
  result.data?.registerCustomApi("finclipLogin", finclipLogin);
}

Individual registration has the highest priority. If an API with the same name exists, the individually registered API will override the globally registered one.

# 1.1.3 Declaring the Custom API in the Mini-Program Configuration File

Create FinClipConf.js in the root directory of the Mini-Program and configure the corresponding custom API, or pass the configuration parameters via loadExtApi.

module.exports = {
  extApi: [
    {
      // General interactive 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 need to be listed.
        url: "",
      },
    },
  ],
};

For more configuration information on the Mini-Program side, please refer to ft.loadExtApi (opens new window).

# 1.1.4 Calling the Custom Mini-Program Asynchronous API

ft.finclipLogin({
  url: "https://www.baidu.com",
  success: function (res) {
    console.log("Call customEvent success");
    console.log(res);
  },
  fail: function (res) {
    console.log("Call customEvent fail");
    console.log(res);
  },
});

# 1.2 Registering a Custom Mini-Program Synchronous API

# 1.2.1 Implementing a Custom Synchronous API

Example of Implementing a Custom Mini-Program Synchronous API

import { IApiManager } from "@finclip/sdk";

interface ILoginApIRes extends IApiManager.IInvokeBaseResponse {} // Define return type

function finclipLoginSync(args: IApiManager.IInvokeArgs): ILoginApIRes {
  /**
   * params Parameters sent by the Mini-Program
   */
  const params = args.params;
  const extInfo = args.extInfo;
  console.log("finclipLoginSync params", JSON.stringify(params));
  // do something
  const res = true;
  // do something end
  // Synchronous API needs to return the result synchronously
  return {
    errMsg: "finclipLoginSync:ok", // Call information. If present, it will be appended to the errMsg field of the callback.
    data: "finclipLoginSync success !!", // Data returned to the Mini-Program
  };
}

# 1.2.2 Registering a Custom Synchronous API

# 1.2.2.1 Global Registration
const instance = FinAppClient.getInstance();
instance?.registerCustomSyncApi("finclipLoginSync", finclipLoginSync);
# 1.2.2.2 Individual Registration
async function startApplet() {
  const result = await client.startApplet({
    appId: "Mini-Program's appId",
    apiServer: "Server address",
  });
  result.data?.registerCustomSyncApi("finclipLoginSync", finclipLoginSync);
}

Individual registration has the highest priority. If an API with the same name exists, the individually registered API will override the globally registered one.

# 1.2.3 Declaring the Custom API in the Mini-Program Configuration File

Create FinClipConf.js in the root directory of the Mini-Program and configure the corresponding custom API, or pass the configuration parameters via loadExtApi.

module.exports = {
  extApi: [
    {
      // General interactive API
      name: "finclipLogin", // Extension API name. This API must be implemented by the native side.
      sync: true, // Whether it is a synchronous API
      params: {
        // Parameter format for the extension API. Only required properties need to be listed.
        url: "",
      },
    },
  ],
};

For more configuration information on the Mini-Program side, please refer to ft.loadExtApi (opens new window).

# 1.2.4 Calling the Custom Mini-Program Synchronous API

const res = ft.finclipLoginSync();
console.log("res:", res); // { errMsg: 'finclipLoginSync:ok',  data: 'customApiSync success !!'        }

# 2. Sending Global Messages from Native to Mini-Program

You can send global messages to the Mini-Program using the following API.

public sendCustomEvent(appId: string, params: IFinApplet.Serializable, apiServer?: string, appRunId: string = ''): boolean

Example Code:

// Host-App
client.sendCustomEvent("appId", { prop1: "app" }, "apiServer");

client.sendCustomEvent("appId", {
  name: "customEventName",
  prop2: "app",
}, "apiServer");
// Mini-Program
ft.onCustomEvent((params) => {
  console.log("ft.onCustomEvent", params); // { prop1: "app" }
});

ft.addCustomEventListener("customEventName", (params) => {
  console.log("ft.addCustomEventListener", params); // { name:"customEventName", prop2: "app" }
});

# 3. Sending Global Messages from Native to WebView Component

You can send global messages to the WebView component using the following API.

/**
 * Sends a global message to the WebView component
 * @param appId Mini-Program ID
 * @param apiName API name
 * @param params Parameters
 * @param apiServer API server address
 * @param appRunId Mini-Program run ID, defaults to empty string
 */
public callWebApi(appId: string, apiName: string, params: IFinApplet.Serializable, apiServer?: string, appRunId: string = ''): boolean;

Example Code:

const appId = 'appId'
const apiName = 'customMethod'
const params = 'message'
client.callWebApi(appId,apiName,params)

# 4. Registering Custom Same-Layer Rendering Components

Starting from version 1.1.9 and Base Library 3.7.3, custom same-layer rendering components are supported.

You can use the XComponentHandler in the proxy method to register custom same-layer rendering components. For specific implementation, please refer to XComponentHandler.

Native developers can render different components based on different tags provided by the Mini-Program. For example:

// Omitted some code
import { FinAppProxyHandlerManager, IApiManager, IFinAppProxy, IFinProxyHandlerItem } from '@finclip/sdk'

@Component
struct XComponentProxy {
  // ...
  @State tag: string = ''

  @Builder
  Button(){
    // ...
  }

  @Builder
  Text(){
    // ...
  }

  build() {
      Column() {
        if(this.tag === 'Button'){
            this.Button()
        }else if(this.tag === 'Text'){
            this.Text()
        }else {
          // ...
        }
      }
      .width(this.xComponentWidth)
      .height(this.xComponentHeight)
  }
}
© FinClip with ❤ , Since 2017