Custom Mini Program APIs

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.
﻿

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

tencent cloud

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

About Tencent Cloud

Help & Support

Resources

User Center

tencent cloud

Sign Up

Log in

Compute

Microservice

Data Migration

Database SaaS Tool

Data Security

Application Security

Big Data

Tencent Big Model

Internet of Things

Stream Services

Cloud Real-time Rendering

Cloud Resource Management

More

Edge Computing

Serverless

Relational Database

Networking

Business Security

Domains & Websites

Face Recognition

AI Platform Service

Middleware

Media On-Demand

Game Services

Management and Audit Tools

Container

Essential Storage Service

Enterprise Distributed DBMS

CDN and Acceleration

Security Services

Enterprise Applications

Voice Technology

Natural Language Processing

Communication

Media Process Services

Education Sevices

Developer Tools

Distributed cloud

Data Process and Analysis

NoSQL Database

Network Security

Cloud Security

Office Collaboration

Image Creation

Optical Character Recognition

Interactive Video Services

Media SDK

Medical Services

Monitor and Operation

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

About Tencent Cloud

Help & Support

Resources

User Center