tencent cloud

Custom Mini Program APIs
Download PDF
Last updated: 2025-07-04 16:48:08
Custom Mini Program APIs
Last updated: 2025-07-04 16:48:08
Download PDF
If a mini program needs capabilities from the superapp that the SDK doesn't support, developers can register custom APIs to enable these capabilities. This allows the mini program to call custom APIs provided by the superapp.

Implement custom APIs in the superapp

The superapp inherits the BaseJsPlugin to implement the custom mini program API capabilities.
Note:
Inherit BaseJsPlugin and define it with the annotation @JsPlugin(secondary = true).
Define a method that can only have one parameter, which must be of type RequestEvent.
Use the annotation @JsEvent("event name") on the method. When the mini program's JavaScript calls "event name," the corresponding method marked with @JsEvent will be called.
@JsEvent supports defining multiple event names.
You can choose to return data synchronously or asynchronously (only one method can be used for the same event).
You can call sendState to return intermediate states to the mini program multiple times. After calling sendState, you must call ok or fail to indicate the end of the entire process.
Example:
@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);
    }

    /**
     * Example of overriding the built-in API (getAppBaseInfo is the SDK’s built-in 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 {
          // Callback intermediate status
          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);
      }
    }
}

Configure custom APIs

Refer to the following template to configure the custom API parameters:
Note:
In the configuration template, the configuration information of the custom API is placed in a JSON file.
The outer extApi field in the JSON file is used to store an array of custom APIs, where each object represents the configuration information for a custom API.
The outer overwriteWxApi field is used to configure whether the custom events should override the default mini program API implementation. When set to true, if the name of the custom API event matches a method name built into the mini program SDK, it will override the SDK's built-in method. Ultimately, the developer's custom API will be called.
Each custom API configuration must include the following three key keywords:
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 "Create API" example.
params: The parameter description for the custom API, where parameters support JSON format and can be nested objects. String-type parameter values should be initialized to an empty string, and numeric-type parameter values should be initialized to 0.
Template:
{
  "extApi": [
    {
      "name": "customSyncEvent",
      "sync": true,
      "params": {
        "name": "",
        "age": 0,
        "object": {
          "key": ""
        }
      }
    },
    {
      "name": "customAsyncEvent2",
      "sync": false,
      "params": {
        "name": "",
        "age": ""
      }
    }
   ], 
   "overwriteWxApi": false
}

Specify the path to the custom API configuration file

Place the defined API configuration file in the project's assets directory (the filename and path can be defined by the developer).

Specify the path to the custom API configuration file in the code
@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 developers call custom APIs

Example:
The superapp defines two custom APIs: customAsyncEvent and getAppBaseInfo, with the following configuration file:

{
  "extApi": [
    {
      "name": "customSyncEvent",
      "sync": true,
      "params": {
        "name": "",
        "age": ""
      }
    },
    {
      "name": "customAsyncEvent",
      "sync": false,
      "params": {
        "name": "",
        "age": ""
      }
    },
    {
      "name": "getAppBaseInfo",
      "sync": false,
      "params": {
      }
    }
  ],
  "overwriteWxApi": true
}
Mini program developers can access custom APIs in the following ways.
wx.customAsyncEvent({"name":"123","age":"18"})
wx.getAppBaseInfo() // This 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, when the mini program calls wx.getAppBaseInfo, it will invoke the custom implementation of getAppBaseInfo defined by the superapp.

Troubleshoot custom API issues

If there are errors when calling custom APIs, please refer to Android FAQs .

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback