tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Tencent Cloud Mini Program Platform
    Documentation
    Download PDF

    Custom mini program APIs

    Last updated: 2024-06-27 10:58:43
    Download PDF
      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.

      Contact Us
      Technical Support

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

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy