# 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:
- Registering custom APIs for use by native Mini-Programs;
- 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:
- Implement the custom API
- Register the custom API
- Declare the custom API in the Mini-Program configuration
- 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)
}
}