Custom Mini Program APIs

Recent Pages

Custom Mini Program APIs

Last updated: 2024-11-21 17:29:23

If a mini program needs to call certain capabilities provided by the host app that are not implemented or cannot be implemented by the mini program SDK, developers can register custom APIs to enable these capabilities.
Implementing custom APIs in the host app
The host app implements the custom mini program API capability by inheriting the BaseJsPlugin.
Note：
Extend `BaseJsPlugin` and define it with the annotation @JsPlugin(secondary = true).
Define a method, which can have only one parameter of the `RequestEvent` type.
Then, define the annotation @JsEvent("event name") in the method. When the mini program JS calls the "event name", the method modified by @JsEvent will be called.
@JsEvent supports defining multiple event names.
The data can be returned synchronously or asynchronously (only one method can be selected for the same event).
You can use `sendState` to send multiple intermediate states to the mini program. After the final sendState call, you must call either ok or fail to indicate the end of the process.
Sample code:
@JsPlugin(secondary = true)
public class CustomPlugin extends BaseJsPlugin {
   @JsEvent("customAsyncEvent")
   public void custom(final RequestEvent req) {
       // Get the parameters
       //req.jsonParams
       // Return the data asynchronously
       //req.fail();
       //req.ok();
       JSONObject jsonObject = new JSONObject();
       try {
           jsonObject.put("key", "test");
       } catch (JSONException e) {
           e.printStackTrace();
       }
       req.ok(jsonObject);
    }
 
   @JsEvent("customSyncEvent")
   public String custom1(final RequestEvent req) {
       // Get the parameters
       //req.jsonParams
       //Return the data synchronously
       JSONObject jsonObject = new JSONObject();
       try {
           jsonObject.put("key", "value");
       } catch (JSONException e) {
           throw new RuntimeException(e);
       }
       return req.okSync(jsonObject);
    }
 
   /**
    * Test coverage system API
    * @param req
    */
   @JsEvent("getAppBaseInfo")
   public void getAppBaseInfo(final RequestEvent req) {
       // Get the parameters
       //req.jsonParams
       // Return the data asynchronously
       //req.fail();
       //req.ok();
       JSONObject jsonObject = new JSONObject();
       try {
           jsonObject.put("key", "test");
       } catch (JSONException e) {
           e.printStackTrace();
       }
       req.ok(jsonObject);
    }
    
   @JsEvent("testState")
   public void testState(final RequestEvent req) {
 
     try {
         //Call back intermediate state 
         req.sendState(req, new JSONObject().put("progress", 1));
         req.sendState(req, new JSONObject().put("progress", 30));
         req.sendState(req, new JSONObject().put("progress", 60));
         req.sendState(req, new JSONObject().put("progress", 100));
     } catch (JSONException e) {
         e.printStackTrace();
     }
 
     JSONObject jsonObject = new JSONObject();
     try {
         jsonObject.put("key", "test");
         req.ok(jsonObject);
     } catch (JSONException e) {
       throw new RuntimeException(e);
     }
    }
}
Configurecustom APIs
Refer to the following template to configure the custom API parameters: 
Note：
In the configuration template, custom API information is stored in a JSON file.
The extApi field in the outer layer of the JSON file holds an array of custom APIs. Each object within extApi represents the configuration of a custom API.
The overwriteWxApi field in the outer layer of the JSON file determines whether custom events override the default mini program API implementation. 
Setting this to true means the SDK's built-in mini program APIs will be overridden.
Each custom API configuration must include the following three key attributes: 
name: The event name of the custom API, which must match the event name defined by @JsEvent.
sync: Indicates whether the call is synchronous and should be consistent with the return method in the "Creating API" example.
params: Describes the parameters of the custom API.
Template：
{
 "extApi": [
    {
      //Event name, must match the event defined in the "Create API" example with @JsEvent
     "name": "customSyncEvent", 
     //Whether the call is synchronous, consistent with the return method in the "Creating API" example
     "sync": true,
     //Define parameters
     //a. JSON format can be nested
     //b. string parameter value can be to ""
     //c.  numeric parameter value can be to 0
     "params": {
       "name": "",
       "age": 0,
       "object": {
         "key": "",
       }
      }
   },
     {
     "name": "customAsyncEvent2",
     "sync": false,
     "params": {
       "name": "",
       "age": ""
     }
  ],
 //true: If the custom API event name matches a built-in method name in the mini program SDK, it will override the SDK's built-in API.   
 //API, and the final call will invoke the developer's custom API.
 "overwriteWxApi": false
}
Specifying the custom API configuration file path
Place the defined API configuration file in the project's assets directory (the file name and path can be defined by the developer).
﻿
Code to specify custom API configuration files
@ProxyService(proxy = MiniAppProxy.class)
public class MiniAppProxyImpl extends BaseMiniAppProxyImpl {
     @Override
   public MiniConfigData configData(Context context, int configType, JSONObject params) {
       if(configType == MiniConfigData.TYPE_CUSTOM_JSAPI) {
           //Custom JsApi configuration
           MiniConfigData.CustomJsApiConfig customJsApiConfig = new MiniConfigData.CustomJsApiConfig();
           customJsApiConfig.jsApiConfigPath = "tcmpp/custom-config.json";
 
           return new MiniConfigData
                    .Builder()
                   .customJsApiConfig(customJsApiConfig)
                    .build();
       }
     
     return null;
}
Mini program developer calling custom API
Example
The host app defines two custom APIs: customAsyncEvent and getAppBaseInfo. The configuration file is as follows: 
{
  "extApi": [
    {
      "name": "customSyncEvent",
      "sync": true,
      "params": {
        "name": "",
        "age": ""
      }
    },
    {
      "name": "customAsyncEvent",
      "sync": false,
      "params": {
        "name": "",
        "age": ""
      }
    },
    {
      "name": "getAppBaseInfo",
      "sync": false,
      "params": {
      }
    }
  "overwriteWxApi": true
}
The mini program developers can access custom APIs as follows:
wx.customAsyncEvent({"name":"123","age":"18"})
wx.getAppBaseInfo()//his will override the system API and call the custom API.
Note：
Since the overwriteWxApi property in the custom API configuration file is set to true, calling wx.getAppBaseInfo in the mini program will invoke the host application's custom implementation of getAppBaseInfo.
Troubleshooting custom APIs
If there are errors when calling custom APIs, see Android FAQs.
﻿

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support

tencent cloud

Recent Pages

Custom Mini Program APIs

Implementing custom APIs in the host app

Configurecustom APIs

Specifying the custom API configuration file path

Mini program developer calling custom API

Troubleshooting custom APIs

Was this page helpful?

Was this page helpful?

tencent cloud

Sign Up

Log in

Recent Pages

Custom Mini Program APIs

Implementing custom APIs in the host app

Configurecustom APIs

Specifying the custom API configuration file path

Mini program developer calling custom API

Troubleshooting custom APIs

Was this page helpful?

Was this page helpful?