# Mini-Program Management
Mini-Program Management mainly introduces the APIs for operating Mini-Programs, including: opening a Mini-Program, closing a Mini-Program
The following APIs are all methods on the
FinAppClientinstance returned by calling theFinAppClient.initmethod. Theclientin the example code is the instance ofFinAppClient. Any special cases will be noted in the corresponding API description.
# 1. Opening a Mini-Program
Different scenarios require different APIs for opening Mini-Programs. Therefore, we provide multiple different APIs for opening Mini-Programs.
Opening an online Mini-Program: Generally, only the Mini-Program ID and server address are needed. This API can only open the official version of the Mini-Program.
Opening a Mini-Program via QR Code: This scenario involves scanning the QR code on the Mini-Program platform, obtaining the content from the QR code, and then using that content to open the Mini-Program. QR codes for official, trial, review, development, and preview versions of Mini-Programs can all be opened using this API.
# 1.1 Standard Opening of a Mini-Program
The following types are all under the IFinApplet namespace, such as IFinApplet.IAppletRequest, IFinApplet.IQrCodeRequest
IAppletRequest
| Attribute | Type | Required | Description |
|---|---|---|---|
| appId | string | Yes | Mini-Program ID |
| apiServer | string | Yes | Server to which the Mini-Program belongs |
| startParams | IStartParams | No | Mini-Program startup parameters |
| offlineLibraryPath | string | No | Offline Mini-Program package path, can be a sandbox file path or rawfile path, speeds up initial startup |
| offlineFrameworkZipPath | string | No | Offline base library compressed package path, can be a sandbox file path or rawfile path, speeds up initial startup |
| sequence | number | No | Mini-Program index |
| hideCapsuleCloseButton | boolean | No | Whether to hide the close button in the Mini-Program capsule |
| hideCapsuleMoreButton | boolean | No | Whether to hide the more button in the Mini-Program capsule |
| hideTransitionCloseButton | boolean | No | Whether to hide the close button in the loading page capsule |
| appletThemeStyle | IFinApplet.IThemeStyle | No | Mini-Program theme style, same as UIConfig.themeStyle |
| backgroundColorContent | string | No | Background color of the Mini-Program page container |
| enableWatermark | boolean | No | Whether to display a watermark, default is false |
| enableScreenShot | boolean | No | Whether to allow screenshots and screen recording, default is true |
| forceUpdate | boolean | No | Whether to force opening the latest version, default is false |
| reLaunchMode | IFinApplet.ReLaunchMode | No | Mode for executing reLaunch during Mini-Program hot start. Enum type, default is [IFinApplet.ReLaunchMode.PARAMS_EXIST], meaning reLaunch is executed as long as there are startup parameters (startup parameters are not null and not empty strings, regardless of whether they are the same as the previous startup parameters) |
| appletAutoAuthorize | boolean | No | Whether to allow the SDK to automatically grant permissions to the Mini-Program. Default is false. If set to true, the permission dialog will not be displayed when permissions are triggered for the first time in the Mini-Program |
| extraInfo | object | No | Business transparent transmission extension information |
IStartParams
| Attribute | Type | Required | Description |
|---|---|---|---|
| path | string | No | Path of the page to start |
| query | string | No | Startup parameters |
| scene | number | No | Startup scene value |
| shareDepth | number | No | Share depth |
| referrerInfo | IFinApplet.IReferrerInfo | No | Referrer information |
# API
/**
* Starts a Mini-Program based on the provided request.
* @param request - The Mini-Program request details.
* @returns A result containing the Mini-Program client or an error.
*/
public startApplet(request: IFinApplet.IAppletRequest): Promise<IFinApplet.IFinAppResult<AppletClient>>
# 1.1.1 Opening a Mini-Program (Basic Parameters)
# Example Call
client.startApplet({
appId: 'appId',
apiServer: 'apiServer'
})
# 1.1.2 Opening a Mini-Program (With Startup Parameters)
# Example Call
client.startApplet({
appId: 'appId',
apiServer: 'apiServer',
startParams: {
path:'/pages/index/index',
query: "aaa=test&bbb=123"
}
})
# 1.2 Opening a Mini-Program via QR Code
Scan the QR code in the platform for the Mini-Program, and pass the parsed QR code content to the interface to open the Mini-Program.
IQrCodeRequest
| Attribute | Type | Required | Description |
|---|---|---|---|
| qrcode | string | Yes | QR code content |
| hideCapsuleCloseButton | boolean | No | Whether to hide the close button in the Mini-Program capsule |
| hideCapsuleMoreButton | boolean | No | Whether to hide the more button in the Mini-Program capsule |
| appletThemeStyle | IFinApplet.IThemeStyle | No | Mini-Program theme style, same as UIConfig.themeStyle |
| backgroundColorContent | string | No | Background color of the Mini-Program page container |
| enableWatermark | boolean | No | Whether to display a watermark, default is false |
| enableScreenShot | boolean | No | Whether to allow screenshots and screen recording, default is true |
| forceUpdate | boolean | No | Whether to force opening the latest version, default is false |
| reLaunchMode | IFinApplet.ReLaunchMode | No | Mode for executing reLaunch during Mini-Program hot start. Enum type, default is [IFinApplet.ReLaunchMode.PARAMS_EXIST], meaning reLaunch is executed as long as there are startup parameters (startup parameters are not null and not empty strings, regardless of whether they are the same as the previous startup parameters) |
# API
/**
* Starts a Mini-Program using a QR code.
* @param request - The QR code request details.
* @returns A result containing the Mini-Program client or an error.
*/
public startAppletByQrCode(request: IFinApplet.IQrCodeRequest): Promise<IFinApplet.IFinAppResult<AppletClient>>
# Example Call
client.startAppletByQrCode({
qrcode: 'qrcode'
})
# 1.3 Mini-Program Hot Start
If a Mini-Program has been opened before and is opened again without opening a new version, a hot start will be performed, meaning the already opened Mini-Program is directly invoked. Whether the page is reloaded depends on the reLaunch mode set when starting the Mini-Program and the startup parameters:
- If the reLaunch mode for hot start is
IFinApplet.ReLaunchMode.PARAMS_EXIST, reLaunch is executed as long as there are startup parameters (any ofpath,query, orreferrerInfoin the startup parameters is not null and not an empty string, regardless of whether they are the same as the previous startup parameters). - If the reLaunch mode for hot start is
IFinApplet.ReLaunchMode.ONLY_PARAMS_DIFF, reLaunch is executed only when there are startup parameters (any ofpath,query, orreferrerInfoin the startup parameters is not null and not an empty string) and they are different from the previous startup parameters. - If the reLaunch mode for hot start is
IFinApplet.ReLaunchMode.ALWAYS, reLaunch is always executed regardless of the startup parameters (whether there are startup parameters or not, and regardless of whether they are the same as the previous startup parameters). - If the reLaunch mode for hot start is
IFinApplet.ReLaunchMode.NEVER, reLaunch is never executed regardless of the startup parameters (whether there are startup parameters or not, and regardless of whether they are the same as the previous startup parameters).
# 2. Closing a Mini-Program
This API does not actually terminate the Mini-Program but moves it to the system background, equivalent to the close button in the top right corner.
# 2.1 Closing a Specified Mini-Program
# API
/**
* Closes a Mini-Program.
* @param appId - The ID of the Mini-Program to close.
* @param apiServer - The API server associated with the Mini-Program.
* @param appRunId - The Mini-Program run ID, default is an empty string.
* @returns A result indicating success or failure.
*/
public closeApplet(appId: string, apiServer?: string, appRunId: string = ''): Promise<IFinApplet.IFinAppResult<boolean>>
# Example Call
client.closeApplet('appId', 'apiServer')
# 2.2 Closing All Mini-Programs
# API
/**
* Closes all Mini-Programs without deleting their resources.
* @returns A result indicating success or failure.
*/
public closeAllApplet(): Promise<IFinApplet.IFinAppResult<boolean>>
# Example Call
client.closeAllApplet()
# 3. Terminating a Mini-Program
# 3.1 Terminating a Specified Mini-Program
# API
/**
* Terminates a specified Mini-Program.
* @param appId - The ID of the Mini-Program to terminate.
* @param apiServer - The API server associated with the Mini-Program.
* @param appRunId - The Mini-Program run ID, default is an empty string.
* @returns A result indicating success or failure.
*/
public clearApplet(appId: string, apiServer?: string, appRunId: string = ''): Promise<IFinApplet.IFinAppResult<boolean>>
# Example Call
client.clearApplet('appId', 'apiServer')
# 3.2 Terminating All Mini-Programs
# API
/**
* Terminates all Mini-Programs.
* @returns A result indicating success or failure.
*/
public clearAllApplet(): Promise<IFinApplet.IFinAppResult<boolean>>
# Example Call
client.clearAllApplet()
# 4. Deleting Mini-Program Information
Because running a Mini-Program caches the Mini-Program package and information locally, subsequent openings will prioritize the cache, making the opening process very fast. Therefore, if you want to delete all information of a Mini-Program, you can use the following APIs to delete a specific Mini-Program or all Mini-Programs.
# 4.1 Deleting a Specified Mini-Program
# API
/**
* Removes a Mini-Program from the local cache.
* @param appId - The ID of the Mini-Program to remove.
* @param apiServer - The API server associated with the Mini-Program.
* @param appRunId - The Mini-Program run ID, default is an empty string.
* @returns A result indicating success or failure.
*/
public removeAppletFromLocalCache(appId: string, apiServer?: string, appRunId: string = ''): Promise<IFinApplet.IFinAppResult<boolean>>
# Example Call
client.removeAppletFromLocalCache('appId', 'apiServer')
# 4.2 Deleting All Mini-Programs
# API
/**
* Removes all Mini-Programs and base library information from the local cache.
* @returns A result indicating success or failure.
*/
public async removeAllAppletFromLocalCache(): Promise<IFinApplet.IFinAppResult<boolean>>
# Example Call
client.removeAllAppletFromLocalCache()
# 5. Batch Downloading Mini-Programs
Querying and downloading Mini-Program packages to the local device in advance can reduce the time taken for the first startup of a Mini-Program.
# API
/**
* Batch queries Mini-Program update information and downloads Mini-Program packages as needed.
* @param apiServer - The Mini-Program server address registered in the initialization configuration.
* @param appIds - An array of Mini-Program IDs to query.
* @param isBatchDownloadApplets - Whether to download Mini-Program packages that need updating, default is false.
* @returns The batch query or download result.
*/
public downloadApplets(
apiServer: string,
appIds: string[],
isBatchDownloadApplets: boolean = false
): Promise<IFinApplet.IFinAppResult<IFinApplet.IAppletDownLoadInfo[]>>
| Parameter | Type | Required | Description |
|---|---|---|---|
| apiServer | string | Yes | The server address configured in IFinAppConfig.IStoreConfig. If not registered, the errMsg in the call result will indicate that the server does not exist. |
| appIds | string[] | Yes | An array of Mini-Program IDs to process in batch. |
| isBatchDownloadApplets | boolean | No | Whether to download Mini-Program packages that are not available locally or need updating, default is false. When set to false, only queries and writes Mini-Program information without downloading the package. |
IFinApplet.IAppletDownLoadInfo
| Attribute | Type | Required | Description |
|---|---|---|---|
| appId | string | Yes | Mini-Program ID. |
| success | boolean | Yes | Whether the current processing was successful. false if the interface returns an error or the package download fails. |
| needUpdate | boolean | Yes | Whether an update is detected as needed. false if a version with the same file MD5 is already cached locally. |
# Example Call
const result = await client.downloadApplets(
'https://api.example.com',
['appletId1', 'appletId2'],
true
)
if (result.data) {
// Each item contains appId, success, and needUpdate
console.info(JSON.stringify(result.data))
} else {
console.error(result.errMsg)
}
# 6. Pre-downloading the Base Library
Pre-downloading the base library can reduce the download time during the first startup of a Mini-Program. Configure enablePreloadFramework in IFinAppConfig.IStoreConfig; the default value for this field is true. After initializing the SDK, the base library will be asynchronously pre-downloaded when the server completes online verification. It will not be re-downloaded if the base library information already exists locally or if offline mode is used.
After setting
enablePreloadFrameworktofalse, the base library will not be pre-downloaded during the initialization phase. However, when callingdownloadApplets, the SDK will still attempt to download the base library first before querying or downloading the Mini-Program.
# Configuration Example
import { FinAppClient, IFinAppConfig } from '@finclip/sdk'
const finAppConfig: IFinAppConfig.IFinAppConfig = {
finStoreConfigs: [{
apiServer: 'https://api.example.com',
sdkKey: 'sdkKey',
sdkSecret: 'sdkSecret',
cryptType: 'sm',
// Enable base library pre-download, default value is true
enablePreloadFramework: true
}]
}
const client = FinAppClient.init(finAppConfig, this.context, 'AppletAbility')