tencent cloud

Tencent Cloud Super App as a Service

문서Tencent Cloud Super App as a Service

Customizing Mini Program APIs

Download
포커스 모드
폰트 크기
마지막 업데이트 시간: 2026-03-20 17:56:26
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
        // Get current mini program information
        // mMiniAppContext.getMiniAppInfo();
        // 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
        // Get current mini program information
        // mMiniAppContext.getMiniAppInfo();
        // 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
        // Get current mini program information
        // mMiniAppContext.getMiniAppInfo();
        // 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 states
          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);
      }
    }
}

Calling methods in the mini program

// Asynchronous API call
var opts = {
   api_name: 'customAsyncEvent',
   progress: function(res) {
     // Code to listen for sendState status updates
   },
   success: function(res) {},
   fail: function(res) {},
   complete: function(res) {},
   data: { // Input parameters
      name : 'kka',
      age : 22
   }
 }
 wx.invokeNativePlugin(opts); 

// Synchronous API call
var opts = {
   api_name: 'customSyncEvent',
   sync:true
}
var rst = wx.invokeNativePlugin(opts);

Advanced usage

Calling custom APIs using the wx.api method

Custom APIs can be configured in the terminal app's configuration file. In the mini program, they can be called directly by calling wx.api.
1. 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.
Here is the template:
{
  "extApi": [
    {
      "name": "customSyncEvent",
      "sync": true,
      "params": {
        "name": "",
        "age": 0,
        "object": {
          "key": ""
        }
      }
    },
    {
      "name": "customAsyncEvent2",
      "sync": false,
      "params": {
        "name": "",
        "age": ""
      }
    }
   ], 
   "overwriteWxApi": false
}
2. 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;
}
3. Mini program developers calling 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.
var opts = {
    progress: function(res) {},
    success: function(res) {},
    fail: function(res) {},
    complete: function(res) {}
}
wx.testState(opts); 

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.

Start an Activity in a custom API

If your business logic requires launching an Activity inside a custom API to handle certain tasks, you can do so as follows:
1. Add Activity result listener and remove it after handling.
Note:
It is recommended to pair the registration and removal of the listener to avoid memory leaks.
@JsPlugin(secondary = true)
public class CustomPlugin extends BaseJsPlugin {
    @JsEvent("testStartActivityForResult")
    public void testStartActivityForResult(final RequestEvent req) {
      Activity activity = req.activityRef.get();
      TmfMiniSDK.addActivityResultListener(new IActivityResultListener() {
          @Override
          public boolean doOnActivityResult(int requestCode, int resultCode, Intent data) {
              TmfMiniSDK.removeActivityResultListener(this);

              Log.i(ModuleApplet.TAG, data.getStringExtra("key"));
              req.ok();
              return true;
          }
      });
  }
}
2. Start a new Activity.
Note:
When starting the Activity, requestCode must be >=1000000, otherwise it may conflict with the internal requestCode, causing unknown issues.
@JsPlugin(secondary = true)
public class CustomPlugin extends BaseJsPlugin {
    @JsEvent("testStartActivityForResult")
    public void testStartActivityForResult(final RequestEvent req) {
      Activity activity = req.activityRef.get();
      TmfMiniSDK.addActivityResultListener(new IActivityResultListener() {
          @Override
          public boolean doOnActivityResult(int requestCode, int resultCode, Intent data) {
              TmfMiniSDK.removeActivityResultListener(this);

              Log.i(ModuleApplet.TAG, data.getStringExtra("key"));
              req.ok();
              return true;
          }
      });

      // Note: requestCode must be >=1000000, otherwise it may conflict with the internal requestCode, causing unknown issues.
      activity.startActivityForResult(new Intent(activity, TransActivity.class), 1000000);
  }
}

Troubleshoot custom API issues

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


다음 주제: 데이터 처리 및 보안 계약

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백