# 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 FinAppClient instance returned by calling the FinAppClient.init method. The client in the example code is the instance of FinAppClient. 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.

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

  2. 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:

  1. If the reLaunch mode for hot start is IFinApplet.ReLaunchMode.PARAMS_EXIST, reLaunch is executed as long as there are startup parameters (any of path, query, or referrerInfo in the startup parameters is not null and not an empty string, regardless of whether they are the same as the previous startup parameters).
  2. If the reLaunch mode for hot start is IFinApplet.ReLaunchMode.ONLY_PARAMS_DIFF, reLaunch is executed only when there are startup parameters (any of path, query, or referrerInfo in the startup parameters is not null and not an empty string) and they are different from the previous startup parameters.
  3. 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).
  4. 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 enablePreloadFramework to false, the base library will not be pre-downloaded during the initialization phase. However, when calling downloadApplets, 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')
© FinClip with ❤ , Since 2017