tencent cloud

Tencent Cloud Super App as a Service

Release Notes and Announcements
Announcement: Tencent Cloud Mini Program Platform Renamed to Tencent Cloud Super App as a Service on January 2, 2025
Console Updates
Android SDK Updates
iOS SDK Updates
Flutter SDK Updates
IDE Updates
Base Library Updates
Product Introduction
Overview
Strengths
Use Cases
Purchase Guide
Billing Overview
Pay-As-You-Go Billing
Renewal Guide
Service Suspension Instructions
Getting Started
Plan Management
Overview
Console Account Management
Storage Configuration
Acceleration Configuration
Branding Configurations
Platform Features
Console Login
Users and Permission System
Mini Program Management
Mini Game Management
Superapp Management
Commercialization
Platform Management
User Management
Team Management
Operations Management
Security Center
Code Integration Guide
Getting Demo and SDK
Android
iOS
Flutter
Superapp Server
GUID Generation Rules
Mini Program Development Guide
Mini Program Introduction and Development Environment
Mini Program Code Composition
Guide
Framework
Components
API
Server Backend
JS SDK
Base Library
IDE Operation Instructions
Mini Game Development Guide
Guide
API
Server Backend
Practice Tutorial
Mini Program Login Practical Tutorial
Mini Program Subscription Message Practical Tutorial
Payment Practical Tutorial
Ad Integration Practical Tutorial
Mini Game Subscription Message Practical Tutorial
API Documentation
History
Introduction
API Category
Making API Requests
Operation Management APIs
User Management APIs
Team Management APIs
Sensitive API-Related APIs
Role Management APIs
Platform Management APIs
Other Console APIs
Mini Program or Mini Game APIs
Management-Sensitive APIs
Global Domain Management APIs
Superapp APIs
Data Types
Agreements
Service Level Agreement
Data Processing and Security Agreement
SDK Privacy Policy Module
SDK Data Processing and Security Agreement Module
DocumentationTencent Cloud Super App as a ServiceCode Integration GuideAndroidAndroid APICustomizing Mini Program CapabilitiesCustomizing Mini Program APIs

Customizing Mini Program APIs

PDF
Focus Mode
Font Size
Last updated: 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 .


Previous Topic: Mini Program File ManagementNext Topic: Customizing Mini Program View Components

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback