Most mini program content is rendered on a WebView. If you consider the WebView as a separate layer, the system's native components are on a higher layer. These two layers are completely independent, so you can't simply use z-index to control the relative layering of native and non-native components. As shown below, non-native components are on the WebView layer, while native components and cover-view/cover-image are on a higher layer.
Same-layer rendering means using certain technical methods to render native components directly on the WebView layer. In this case, the native component layer no longer exists, and native components are directly mounted to WebView nodes. You can use native components almost like non-native ones, such as using `view` and `image` to overlay native components, using z-index to specify the layer of native components, placing native components in containers like scroll-view, swiper, movable-view, and setting styles via WXSS. The interface hierarchy after enabling "same-layer rendering"
How is same-layer rendering implemented?
On Android, mini programs use Chromium as the WebView rendering layer. The WebView on Android renders separately, producing a complete view. Therefore, other methods are needed to achieve "same-layer rendering." Our research found that Chromium supports the WebPlugin mechanism, a browser kernel plugin mechanism mainly used to parse and describe embed tags. Android's same-layer rendering is implemented based on the embed tag combined with Chromium (customized x5 kernel) extensions.
The general process for same-layer rendering on Android is as follows:
The WebView creates an embed DOM node and specifies the component type.
The Chromium kernel creates a WebPlugin instance and generates a RenderLayer.
The Android client initializes a corresponding native component.
The Android client draws the image of the native component on "SurfaceTexture" that is bound to "RenderLayer".
Notify the Chromium kernel to render the RenderLayer.
The Chromium renders the embed node and displays it on the screen.
This method can be used for rendering native components like map, video, canvas, camera, textarea, and input.
Troubleshooting mini program startup failures
Mini program startup failures can occur for several reasons:
Incorrect CONFIGURATION FILE Path: The configAssetName should be the full path to the file in the assets directory. If the configuration file is in a subdirectory, include the directory path, e.g., server/tcmpp-android-configurations.json.
Modification of configuration file: Do not modify the mini program configuration file, as this will prevent the mini program from running correctly.
Package name mismatch: The packageName in the configuration file must match the application's applicationId. The app will fail to run if they do not match because the packageName is verified during initialization. You can disable package name verification with the following setting:
MiniInitConfig config = builder
.verifyPkg(false)//Ignore the package name check
.build();
Initialization annotation: Ensure that the initialization annotation @ProxyService has generated the ExtProxyServiceScope class.
How does the SDK ensure privacy compliance?
The mini program SDK initializes when the developer calls methods from the TmfMiniSDK class. Therefore, you should call these methods only after the user has agreed to the privacy compliance authorization.
How to troubleshoot customized mini program API errors?
Check if XxxJsPluginScope is generated in the compilation path, as shown below:
Ensure that the event names defined on the client side match the method names called by the mini program. Note that custom mini-program API event names are case-sensitive.
Mini program domain and privacy API validation logic
During usage, the mini program will validate the legality of the API request domain names. If privacy APIs are set in the management backend, authorization checks will also be performed. However, validation is skipped in the following scenarios:
The mini program is running in a non-production version and the mini program debugging is enabled，see mini program debugging.
Modular project support
When multiple modules in a modular project use the @JsPlugin or @ProxyService annotations simultaneously, the following error may occur during the Make Project process:
To support multi-module projects, configure as follows:
1. Add the following code to the build.gradle file of each module using the @JsPlugin or @ProxyService annotation:
android {
defaultConfig {
javaCompileOptions {
annotationProcessorOptions {
//Configure module name: Define a unique name following Android class naming conventions
arguments = [tcmppModuleName: "Demo"]
}
}
}
}
2. Register the module in the initialization code:
@ProxyService(proxy = MiniConfigProxy.class)
public class MiniConfigProxyImpl extends MiniConfigProxy {
@Override
public MiniInitConfig buildConfig() {
MiniInitConfig.Builder builder = new MiniInitConfig.Builder();
//Register all modules defined above; the registerModule parameter should match the tcmppModuleName defined earlier
return builder
How to view SDK log output?
1. Developers can filter SDK logs using the keyword TMF_MINI in the development tools.
2. To view miniprogram JS error logs.
Method 1: Filter JS logs using the keyword MINI_JS_LOG.
Method 2: Use Chrome to debug and check for JS errors in the mini program.
How to enable mini program debugging mode?
To facilitate debugging and viewing log outputs, the client needs to enable the mini program debug entry. Refer to Mini program host customization - "Custom Capsule" getMoreItems implementation.
/**
* Returns the buttons for the capsule's more panel. The extended button IDs should be set within the range [100, 200]; otherwise, the addition is invalid.
* Note: This method is called in the mini program process.
* @param builder
* @
*/
After setting this, the mini program control panel will display a debug button. Click it to enable debug mode, then restart the mini program to enter debug mode.
Does the mini program SDK automatically clear mini program package cache?
No, developers need to manually call the mini program SDK's provided deletion methods to clear the mini programs (Deleting mini programs). If not cleared proactively, the host app's cache will increase as more mini programs are used.
Yes
No
Was this page helpful?