Custom Mini Program SDK APIs

Recent Pages

Custom Mini Program SDK APIs

Last updated: 2024-11-21 17:31:11
To enhance usage scenarios, the mini program SDK exposes certain APIs that can be customized by the host app. This allows the host app to provide unique capabilities to the mini program.
Prerequisite
To customize the mini program SDK APIs, you need to define a custom MiniAppProxy as follows:
Note：
Define an implementation class that extends BaseMiniAppProxy and annotate it with @ProxyService(proxy = MiniAppProxy.class).
@ProxyService(proxy = MiniAppProxy.class)
public class MiniAppProxyImpl extends BaseMiniAppProxy{}
Once the prerequisites are completed, you can customize the mini program SDK APIs. The SDK mainly supports the following types of APIs: 
1. Customizing capsule button feature
1.1 Customizing close button event listener
Customize the close button event listener for the capsule button, allowing the host app to receive callback events when the close button is clicked.
Close button figure: 
﻿
API description: The return value of onCapsuleButtonCloseClick method indicates whether to customise the close button listener or not, a return value of true means customise it, false (default value) means use the default listener.
/**
 * Close option for clicking capsule button
 * Calling environment: child process
 *
 * @param miniAppContext The environment in which the mini programme runs (the mini program process, not the main process).
 * @param onCloseClickedListener Callback when clicking the mini program to close it.
 * @return does not support this interface, please return false
 */
public abstract boolean onCapsuleButtonCloseClick(IMiniAppContext miniAppContext,
        DialogInterface.OnClickListener onCloseClickedListener);
Sample code:
    @Override
    public boolean onCapsuleButtonCloseClick(IMiniAppContext miniAppContext,
                                             DialogInterface.OnClickListener onCloseClickedListener) {
        Log.e("TAG","onCapsuleButtonCloseClick"+miniAppContext.getMiniAppInfo());
        //handle close mini app event
        return true;
    }
1.2 Customising the More Buttons event listener
Customising the event listener of the More button allows the host application to listen to the callback event of the corresponding item when the More button is clicked.
Diagram of the More button:
﻿
﻿
﻿
API description: The getMoreItemSelectedListener method returns a value that indicates more button listeners.
/**
 * Return to Capsule More panel button click listener
 * Calling environment: child process
 *
 * @return listener
 */
public abstract OnMoreItemSelectedListener getMoreItemSelectedListener();
Sample code:
/**
 * Return to Capsule More panel button click listener
 * @return
 * @return
 */
@Override
public OnMoreItemSelectedListener getMoreItemSelectedListener() {
    return new DemoMoreItemSelectedListener();
}
﻿
/**
define of DemoMoreItemSelectedListener
**/
public class DemoMoreItemSelectedListener extends DefaultMoreItemSelectedListener {
    public static final int CLOSE_MINI_APP = 150;

    @Override
    public void onMoreItemSelected(IMiniAppContext miniAppContext, int moreItemId) {
        
        switch (moreItemId) {
            case CLOSE_MINI_APP:
                close(miniAppContext);
                return;
            case OTHER_MORE_ITEM_1:
                miniAppContext.getAttachedActivity().runOnUiThread(new Runnable() {
                    @Override
                    public void run() {
                        Toast.makeText(miniAppContext.getAttachedActivity(), "custom menu click", Toast.LENGTH_SHORT).show();
                    }
                });
                return;
        }
        super.onMoreItemSelected(miniAppContext, moreItemId);
    }

    public void close(IMiniAppContext miniAppContext) {
        Activity activity = miniAppContext.getAttachedActivity();
        if (activity != null && !activity.isFinishing()) {
            boolean moved = activity.moveTaskToBack(true);
            if (!moved) {
                QMLog.e("Demo", "moveTaskToBack failed, finish the activity.");
                activity.finish();
            }
        }
    }
}
1.3 Customising the More Buttons Display List
By the time the user triggers the more buttons click event, the following list of optional extended buttons will pop up, the default list is shown below:
﻿
By overriding MiniAppProxy's getMoreItems method, it is possible to customise the list of buttons for more menu extensions.
API Description:
The return value of getMoreItems method represents the customised list of extension buttons;
The method parameter MoreItemList.Builder is used to add extension buttons, the display order of extension buttons is the same as the add order;
The id attribute of MoreItem is used to distinguish the buttons and needs to be unique.
/**
 * The button that returns the capsule to the More panel, the ID of the extended button needs to be set to a value in the interval [100, 200], otherwise, the addition is invalid.
 * Call environment: child process
 *
 * @param builder
 * @return
 */
public abstract ArrayList<MoreItem> getMoreItems(MoreItemList.Builder builder);
﻿
Warning：
The ID of the extension button needs to be set to a value in the interval [100, 200], otherwise the add is invalid.
Sample code:
@Override
public ArrayList<MoreItem> getMoreItems(IMiniAppContext miniAppContext, MoreItemList.Builder builder) {
    MoreItem item1 = new MoreItem();
    item1.id = ShareProxyImpl.OTHER_MORE_ITEM_1;
    item1.text = getString(miniAppContext, R.string.applet_mini_proxy_impl_other1);
    item1.drawable = R.mipmap.mini_demo_about;
﻿
    MoreItem item2 = new MoreItem();
    item2.id = ShareProxyImpl.OTHER_MORE_ITEM_2;
    item2.text = getString(miniAppContext, R.string.applet_mini_proxy_impl_other2);
    item2.shareKey = SHARE_TWITTER;//Custom sharing key, must be set and unique, with the mini program side call control settings will be used to
    item2.drawable = R.mipmap.mini_demo_about;
﻿
    MoreItem item3 = new MoreItem();
    item3.id = DemoMoreItemSelectedListener.CLOSE_MINI_APP;
    item3.text = getString(miniAppContext, R.string.applet_mini_proxy_impl_float_app);
    item3.drawable = R.mipmap.mini_demo_about;
﻿
    MoreItem item4 = new MoreItem();
    item4.id = ShareProxyImpl.OTHER_MORE_ITEM_INVALID;
    item4.text = getString(miniAppContext, R.string.applet_mini_proxy_impl_out_of_effect);
    item4.drawable = R.mipmap.mini_demo_about;
﻿
    // Self-adjusting order.
    builder.addMoreItem(item1)
            .addMoreItem(item2)
            .addShareQQ("QQ", R.mipmap.mini_demo_channel_qq)
            .addMoreItem(item3)
            .addShareQzone(getString(miniAppContext, R.string.applet_mini_proxy_impl_Qzone),
                    R.mipmap.mini_demo_channel_qzone)
            .addShareWxFriends(getString(miniAppContext, R.string.applet_mini_proxy_impl_wechat_friend),
                    R.mipmap.mini_demo_channel_wx_friend)
            .addShareWxMoments(getString(miniAppContext, R.string.applet_mini_proxy_impl_wechat_group),
                    R.mipmap.mini_demo_channel_wx_moment)
            .addRestart(getString(miniAppContext, R.string.applet_mini_proxy_impl_restart),
                    R.mipmap.mini_demo_restart_miniapp)
            .addAbout(getString(miniAppContext, R.string.applet_mini_proxy_impl_about),
                    R.mipmap.mini_demo_about)
            .addDebug(getString(miniAppContext, R.string.mini_sdk_more_item_debug),
                    R.mipmap.mini_demo_about)
            .addMonitor(getString(miniAppContext, R.string.applet_mini_proxy_impl_performance),
                    R.mipmap.mini_demo_about)
            .addComplaint(getString(miniAppContext, R.string.applet_mini_proxy_impl_complain_and_report),
                    R.mipmap.mini_demo_browser_report)
            .addSetting(getString(miniAppContext, R.string.mini_sdk_more_item_setting),
                    R.mipmap.mini_demo_setting);
﻿
    return builder.build();
}
﻿
private String getString(IMiniAppContext miniAppContext, int id) {
    return miniAppContext.getContext().getString(id);
}
2.  Customised Image Selection
The mini program SDK provides default image selection, which is done by default using the album selector that comes with Android, and is triggered by calling multimedia selection wx.chooseImage in the mini program.
Custom image selection can be achieved by overriding the openChoosePhotoActivity method of BaseMiniAppProxy.
API description. 
Parameter Context: the current activity instance of the mini program;
Parameter maxSelectedNum: maximum number of selected pictures;
Parameter IChoosePhotoListner: callback interface for photo selection;
Return value boolean: a return value of false means using the default image selection implementation, a return value of true means using the customised image selection implementation.
/**
 * Open the selection screen
 *
 * @param context Current Activity
 * @param maxSelectedNum Maximum number of allowable selections
 * @param listner Callback interface
 * @return Do not support this interface, please return false
 */
@Override
public boolean openChoosePhotoActivity(Context context, int maxSelectedNum, IChoosePhotoListner listner) {
Note：
When the image path is returned by the onResult method of IChoosePhotoListner, the image path should be an absolute path.
Sample code:
@Override
public boolean openChoosePhotoActivity(Context context, int maxSelectedNum, IChoosePhotoListner listner) {
    Log.d("TAG","open choose photo activity ");
    Intent intent = new Intent(context, ChoosePhotosActivity.class);
    intent.putExtra("maxCount",maxSelectedNum);
    //not recommand to use static refs,just for example
    ChoosePhotosActivity.setChooseCallBack(listner);
    context.startActivity(intent);
    
    return true;
}


public class ChoosePhotosActivity extends Activity {
   static WeakReference<MiniAppProxy.IChoosePhotoListner>iChoosePhotoListnerWeakReference;
    public static void setChooseCallBack(MiniAppProxy.IChoosePhotoListner choosePhotoListner){
        iChoosePhotoListnerWeakReference = new WeakReference<>(choosePhotoListner);
    }

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        //todo show your choose view
    }

    @Override
    protected void onResume() {
        super.onResume();
        startChooseImage();
    }

    private void startChooseImage(){
        //todo finish choose logic

        //response choose callback
        ArrayList<String>path = new ArrayList<>();
        //todo replace with real path of image
        path.add("picture local absolute path");
        path.add("picture local absolute path2");
        path.add("/data/user/0/com.tencent.tmf.miniapp.demo/files/userfiles/Screenshot_20240311_153916_com.tencent.tmf.miniapp.demo.jpg");
        iChoosePhotoListnerWeakReference.get().onResult(path);
    }
}
3.  Customising image preview
The mini program SDK provides a default image preview implementation, which is triggered when the mini program calls the multimedia selection wx.previewImage.
Custom image preview can be achieved by overriding the openImagePreview method of BaseMiniAppProxy.
The default image preview page is shown below:
﻿
API description: 
Parameter Context: the current activity instance of the mini program;
parameter selectedIndex: position of the selected image in the list;
parameter pathList: list of paths of the images to be displayed;
Return value boolean: a return value of false means use default image to display, a return value of true means use custom image to display.
/**
 * Open the picture preview interface
 * Calling environment: child process
 *
 * @param context Current Activity
 * @param selectedIndex index of the currently selected image
 * @param pathList picture path list
 * @return Do not support this interface, please return false
 */
public abstract boolean openImagePreview(Context context, int selectedIndex, List<String> pathList);
Sample code:
/**
 * Open the picture preview interface
 *
 * @param context Current Activity
 * @param selectedIndex index of the currently selected image
 * @param pathList picture path list
 * @return Do not support this interface, please return false
 */
@Override
public boolean openImagePreview(Context context, int selectedIndex, List<String> pathList) {
    //todo start your image preview 
    Intent intent = new Intent(context, CustomPreviewActivity.class);
    intent.putExtra("curIndex",selectedIndex);
    intent.putStringArrayListExtra("pathList", pathList);
    context.startActivity(intent);
    return true;
}
4. Customising the user information in the authorisation pop-up
When a mini program applies for user information, it will pop up the user authorisation pop-up window; the host application can customize part of the information in the user authorisation pop-up window, including: avatar image and user nickname, as shown in the following figure:
﻿
Customisation can be achieved by overriding the getUserInfo method of BaseMiniAppProxy.
API description: 
Parameter appId: appId of the mini program currently requesting authorisation;
Parameter AsyncResult: used to return user information to the mini program SDK.
/**
 * Get scope.userInfo authorised user information
 * Call environment: subprocess
 *
 * @param appId
 * @param result
 */
@Override
public void getUserInfo(String appId, AsyncResult result)
Sample code:
/**
 * Get scope.userInfo authorised user information
 * Call environment: subprocess
 *
 * @param appId
 * @param result
 */
@Override
public void getUserInfo(String appId, AsyncResult result) {
    JSONObject jsonObject = new JSONObject();
    try {
        //return nickname
        jsonObject.put("nickName", "userInfo Test");;
        //return the avatar url
        jsonObject.put("avatarUrl", "https://gimg2.baidu.com/image_search/src=http%3A%2F%2Fimg.daimg.com%2Fuploads%2Fallimg%2F210114%2F1-210114151951.jpg&refer=http%3A%2F%2Fimg.daimg.com&app=2002&size=f9999,10000&q=a80&n=0&g=0n&fmt=auto?sec=1673852149&t=e2a830d9fabd7e0818059d92c3883017");
        result.onReceiveResult(true, jsonObject);
    } catch (JSONException e) {
        e.printStackTrace();
    }
}
5. Custom Image Loader
Warning:
Since the mini program SDK does not have a default image loader implementation, the loading of images relies on the host application's implementation; if the host application does not implement an icon loader, this will result in abnormal image loading on some pages.
Host app developers, need to implement image loading customisation by overriding the getDrawable method of BaseMiniAppProxy.
API description: 
Parameter context: the context of the mini program process currently requesting authorisation;
parameter source: the source of the image, it can be a local or network image;
parameter width: width of the image;
parameter height: height of the image;
parameter defaultDrawable: the default drawable, used in loading and loading failure;
Return value Drawable: the loaded drawable object.
@Override
public Drawable getDrawable(Context context, String source, int width, int hight, Drawable defaultDrawable) 
Sample code:
@Override
public Drawable getDrawable(Context context, String source, int width, int hight, Drawable defaultDrawable) {
    //Access to access their own ImageLoader
    //sample code to use the open source universalimageloader
    UniversalDrawable drawable = new UniversalDrawable();
    if (TextUtils.isEmpty(source)) {
        return drawable;
    }
    drawable.loadImage(context, source);
    return drawable;
}
6. Custom mini program data storage segregated by account
Override the getAccount method of BaseMiniAppProxy to achieve isolated storage of mini program data.
API description: The return value is the user account (must be unique), the data will be stored in isolation according to the account after setting, it is not recommended to use user sensitive information.
/**
 * user account, must be unique, after setting the data will be stored according to the account isolation, do not recommend the use of user sensitive information
 * Call environment: the main process
 */
@Override
public String getAccount() {
    return "tmf_test";
}
7. Customised Virtual Domains
Mini program to play to the default virtual domain name, this domain name is not a real domain name, in the browser is not accessible, if you need to customise can be set up in accordance with the following configuration.
The default virtual domain name is shown below:
﻿
To customise the virtual domain name, you need to override the configData method of BaseMiniAppProxy and intercept the configType to MiniConfigData.TYPE_DOMAIN to achieve customisation. Mini program to play to the default virtual domain name, this domain name is not a real domain name, in the browser is not accessible, if you need to customise can be set up in accordance with the following configuration.
The default virtual domain name is shown below:
Sample code:
@Override
public MiniConfigData configData(Context context, int configType, JSONObject params) {
    if(configType == MiniConfigData.TYPE_DOMAIN) {
        //Virtual Domain Configuration
        MiniConfigData.DomainConfig domainConfig = new MiniConfigData.DomainConfig();
        domainConfig.domain = "test.com";
﻿
        return new MiniConfigData
                .Builder()
                .domainConfig(domainConfig)
                .build();
    }
    
    return new MiniConfigData
                .Builder()
                .build();
}
8. Customise the userAgent of the WebView in the mini program.
Customisation can be achieved by overriding the configData method of BaseMiniAppProxy and intercepting the configType as MiniConfigData.TYPE_WEBVIEW.
Sample code:
@Override
public MiniConfigData configData(Context context, int configType, JSONObject params) {
    if(configType == MiniConfigData.TYPE_WEBVIEW) {
        //webView userAgent
        String ua = params.optString(MiniConfigData.WebViewConfig.WEBVIEW_CONFIG_UA);
        MiniConfigData.WebViewConfig webViewConfig = new MiniConfigData.WebViewConfig();
        //Set the userAgent that the developer needs to append, note: don't set the original ua into it!
        webViewConfig.userAgent = "key/value";
﻿
        return new MiniConfigData
                .Builder()
                .webViewConfig(webViewConfig)
                .build();
    }
﻿
    return new MiniConfigData
            .Builder()
            .build();
}
9. Customised scanning capabilities
The mini program SDK provides a default scanning implementation (refer to Extension Library Support - Sweep), and also provides an interface for users to customise the code scanning ability.
To customise the scanning ability, you need to override the enterQRCode method of BaseMiniAppProxy.
API description: 
Parameter context: the current context of the mini program process that initiates the code scanning;
parameter onlyFromCamera: if or not only camera is allowed to sweep code;
parameter AsyncResult: the callback of code scanning result;
Return value boolean: true means custom code scanning ability, false means use built-in code scanning ability (need to integrate code scanning extension library).
/**
 * Scanning QR code
 *
 * @param context context
 * @param onlyFromCamera Only allow camera to scan code
 * @param result Scanning result
 * @return true:custom scanning;false:use built-in scanning
 */
@Override
public boolean enterQRCode(Context context, boolean onlyFromCamera, AsyncResult result);
10. Specify the storage path where the mini program saves the file
By overriding the getSaveFileDir method of BaseMiniAppProxy, we can implement the mini program API to save pictures and videos to the specified directory in the system album.
Sample code:
/**
 * Specify the directory where the mini program API saves images and videos to the system albums
 *
 */
public  String getSaveFileDir(){
return "myapp";
}
Note：
The default path is tcmpp.
11. Listening to the mini program lifecycle
You can listen to the mini program lifecycle by overriding the onAppStateChange method of BaseMiniAppProxy.
API description: 
Parameter appState: life cycle state of the current mini program, refer to AppState;
parameter MiniAppEvent: life cycle event of the current mini program.
/**
 * Mini-program lifecycle event callbacks
 * Call context environment: main process UI threads
 *
 * @param appState event state
 * @param event event
 */
public abstract void onAppStateChange(@AppState int appState, MiniAppEvent event);
12. Customising the base library update policy and listening
You can override BaseMiniAppProxy's isUpdateBaseLib method to listen for updates to the mini program's base library.
API description: 
You can override BaseMiniAppProxy's isUpdateBaseLib method to listen for updates to the mini program's base library.
/**
 * Whether or not to update when the base library detects an update
 * @param context
 * @param data Base library information data
 * @return true:update;false:don't update, default is true
 */
public abstract boolean isUpdateBaseLib(Context context, JSONObject data);
﻿