This module allows you to separate specific functions and resources from the basic module of an app and include them in extended modules. Users can dynamically download the extended modules when using the app. On-demand feature distribution provides functions such as checking whether a module has been installed, requesting on-demand loading, monitoring the download progress, displaying mobile data reminders, and canceling on-demand loading.
Exceptions need to be captured when an API is called.
Start version: 4.1.0(11)
Module installation information.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
moduleName | string | Yes | No | Module name. |
moduleType | Yes | Yes | Module type. NOTE: When the value of installStatus is 1, moduleType will return 0 by default, indicating an unknown type. | |
installStatus | Yes | No | Module installation result. |
Results of calling APIs for initiating requests, registering listeners, and deregistering listeners.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
code | Yes | No | API call result code. | |
taskStatus | Yes | No | Status code of an on-demand download task. | |
taskId | string | Yes | Yes | ID of an on-demand download task. The default value is 0. |
desc | string | Yes | No | API call result description. The default value is "". |
modules | string[] | Yes | Yes | List of module names in a download task. The default value is []. |
totalSize | number | Yes | Yes | Total size of modules to be downloaded, in bytes. The default value is 0. |
downloadedSize | number | Yes | Yes | Downloaded size, in bytes. The default value is 0. |
Enumerated status codes contained in the installation result.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Name | Value | Description |
|---|---|---|
INSTALLED | 0 | The specified module has been installed. |
NOT_INSTALLED | 1 | The specified module has not been installed. |
Enumerated result codes of calling APIs for adding modules, canceling download, and displaying mobile data reminders.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Name | Value | Description |
|---|---|---|
SUCCESS | 0 | Successful. |
FAILURE | 1 | Failed. |
Enumerated result codes of calling APIs for initiating requests, registering listeners, and deregistering listeners.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Name | Value | Description |
|---|---|---|
MODULE_ALREADY_EXISTS | -8 | The specified module already exists. |
MODULE_UNAVAILABLE | -7 | The module to be downloaded does not exist or does not adapt to the device. |
INVALID_REQUEST | -6 | The request is invalid because the information contained in the request is incorrect. |
NETWORK_ERROR | -5 | Request failed due to a network exception. |
INVOKER_VERIFICATION_FAILED | -4 | The caller information is abnormal. |
FOREGROUND_REQUIRED | -3 | On-demand loading is allowed only when the app is running in the foreground. |
ACTIVE_SESSION_LIMIT_EXCEEDED | -2 | The request is denied because at least one download task is undergoing. |
FAILURE | -1 | Failed. |
SUCCESS | 0 | Successful. |
DOWNLOAD_WAIT_WIFI | 1 | Mobile data is used. Call showCellularDataConfirmation to prompt users to confirm whether to use mobile data for download. |
Enumerated status codes of download tasks, returned by APIs for initiating requests, registering listeners, and deregistering listeners.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Name | Value | Description |
|---|---|---|
CREATE_TASK_FAILED | -4 | Failed to create a download task. |
HIGHER_VERSION_INSTALLED | -3 | A same or a later version exists on the user's device. |
TASK_ALREADY_EXISTS | -2 | The download task already exists. |
TASK_UNFOUND | -1 | No download task exists. |
TASK_CREATED | 0 | A download task is created successfully. |
DOWNLOADING | 1 | Downloading. |
DOWNLOAD_PAUSING | 2 | Paused. |
DOWNLOAD_WAITING | 3 | Pending download. |
DOWNLOAD_SUCCESSFUL | 4 | Download completed. |
DOWNLOAD_FAILED | 5 | Download failed. |
DOWNLOAD_WAIT_WIFI | 6 | Scheduled to download with Wi-Fi. |
INSTALL_WAITING | 20 | Waiting to install. |
INSTALLING | 21 | Installing. |
INSTALL_SUCCESSFUL | 22 | Installation completed. |
INSTALL_FAILED | 23 | Installation failed. |
getInstalledModule(moduleName: string): InstalledModule
Queries module installation information.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Parameters:
Parameter | Type | Mandatory | Description |
|---|---|---|---|
moduleName | string | Yes | Name of the module to be obtained. |
Returns:
Type | Description |
|---|---|
Module installation information. |
Error codes:
For details about the error codes, please refer to ArkTS API Error Codes.
Error Code | Error Message |
|---|---|
401 | Parameter error. |
1006500001 | Failed to invoke the BMS. |
Example:
import { moduleInstallManager } from '@kit.StoreKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
try {
const moduleInfo: moduleInstallManager.InstalledModule = moduleInstallManager.getInstalledModule('AModule');
hilog.info(0, 'TAG', 'Succeeded in getting installedModule moduleInfo' );
} catch (error) {
hilog.error(0, 'TAG', `getting installedModule onError.code is ${error.code}, message is ${error.message}`);
} Parent class object of the controller in on-demand loading.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Parent class object of an on-demand loading request.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Implements on-demand loading and provides the capability of creating on-demand loading request objects. This method extends InstallProvider.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
createModuleInstallRequest(context: common.UIAbilityContext | common.ExtensionContext): ModuleInstallRequest
Creates an on-demand loading request object. You can set request parameters through the return value.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Parameters:
Parameter | Type | Mandatory | Description |
|---|---|---|---|
context | Yes | Context of the app that calls the API. |
Returns:
Type | Description |
|---|---|
On-demand download request object. |
Error codes:
For details about the error codes, please refer to Universal Error Codes.
Error Code | Error Message |
|---|---|
401 | Parameter error. |
Example:
import { moduleInstallManager } from '@kit.StoreKit';
import type { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
try {
const myModuleInstallProvider: moduleInstallManager.ModuleInstallProvider =
new moduleInstallManager.ModuleInstallProvider();
const context: common.UIAbilityContext | common.ExtensionContext = getContext(this) as common.UIAbilityContext;
const myModuleInstallRequest: moduleInstallManager.ModuleInstallRequest =
myModuleInstallProvider.createModuleInstallRequest(context);
} catch (error) {
hilog.error(0, 'TAG', `createModuleInstallRequest onError.code is ${error.code}, message is ${error.message}`);
} On-demand download request object, which extends InstallRequest.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
addModule(moduleName: string): ReturnCode
Adds the name of the module to be loaded.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Parameters:
Parameter | Type | Mandatory | Description |
|---|---|---|---|
moduleName | string | Yes | Module name. |
Returns:
Type | Description |
|---|---|
API call result code. |
Error codes:
For details about the error codes, please refer to Universal Error Codes.
Error Code | Error Message |
|---|---|
401 | Parameter error. |
Example:
import { moduleInstallManager } from '@kit.StoreKit';
import type { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
try {
const myModuleInstallProvider: moduleInstallManager.ModuleInstallProvider =
new moduleInstallManager.ModuleInstallProvider();
const context: common.UIAbilityContext | common.ExtensionContext = getContext(this) as common.UIAbilityContext;
const myModuleInstallRequest: moduleInstallManager.ModuleInstallRequest =
myModuleInstallProvider.createModuleInstallRequest(context);
const aResult: moduleInstallManager.ReturnCode = myModuleInstallRequest.addModule('AModule');
const bResult: moduleInstallManager.ReturnCode = myModuleInstallRequest.addModule('BModule');
hilog.info(0, 'TAG', 'Succeeded in getting aResult:' + aResult + ' bResult:' + bResult);
} catch (error) {
hilog.error(0, 'TAG', `addModule onError.code is ${error.code}, message is ${error.message}`);
} fetchModules(moduleInstallRequest: ModuleInstallRequest): Promise<ModuleInstallSessionState>
Requests on-demand loading and returns the result asynchronously through a promise.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Parameters:
Parameter | Type | Mandatory | Description |
|---|---|---|---|
moduleInstallRequest | Yes | On-demand loading request object. |
Returns:
Type | Description |
|---|---|
Promise<ModuleInstallSessionState> | Result of calling the API for initiating requests, registering listeners, or deregistering listeners, returned through a promise. |
Error codes:
For details about the error codes, please refer to ArkTS API Error Codes.
Error Code | Error Message |
|---|---|
401 | Parameter error. |
1006500004 | SA connection failed. |
1006500008 | Write param into container failed. |
1006500009 | Request to service error. |
1006500010 | Response from service cannot be recognized. |
Example:
import { moduleInstallManager } from '@kit.StoreKit';
import type { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
try {
const myModuleInstallProvider: moduleInstallManager.ModuleInstallProvider =
new moduleInstallManager.ModuleInstallProvider();
const context: common.UIAbilityContext | common.ExtensionContext = getContext(this) as common.UIAbilityContext;
const myModuleInstallRequest: moduleInstallManager.ModuleInstallRequest =
myModuleInstallProvider.createModuleInstallRequest(context);
myModuleInstallRequest.addModule('AModule');
myModuleInstallRequest.addModule('BModule');
moduleInstallManager.fetchModules(myModuleInstallRequest)
.then((data: moduleInstallManager.ModuleInstallSessionState) => {
hilog.info(0, 'TAG', 'Succeeded in fetching modules success data.' );
})
} catch (error) {
hilog.error(0, 'TAG', `fetching modules onError.code is ${error.code}, message is ${error.message}`);
} cancelTask(taskId: string): ReturnCode
Cancels a download task.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Parameters:
Parameter | Type | Mandatory | Description |
|---|---|---|---|
taskId | string | Yes | ID of the download task. |
Returns:
Type | Description |
|---|---|
API call result code. |
Error codes:
For details about the error codes, please refer to ArkTS API Error Codes.
Error Code | Error Message |
|---|---|
401 | Parameter error. |
1006500007 | The specified service extension connect failed. |
1006500008 | Write param into container failed. |
1006500009 | Request to service error. |
1006500010 | Response from service cannot be recognized. |
Example:
import { moduleInstallManager } from '@kit.StoreKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
try {
// taskId is a field in ModuleInstallSessionState returned by fetchModules.
const taskId: string = '********';
const rtnCode: moduleInstallManager.ReturnCode = moduleInstallManager.cancelTask(taskId);
hilog.info(0, 'TAG', "Succeeded in getting result:" + rtnCode);
} catch (error) {
hilog.error(0, 'TAG', `cancelTask onError.code is ${error.code}, message is ${error.message}`);
} showCellularDataConfirmation(context: common.UIAbilityContext | common.ExtensionContext,taskId: string): ReturnCode
Displays a mobile data reminder.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Parameters:
Parameter | Type | Mandatory | Description |
|---|---|---|---|
context | Yes | Context. Currently, only UIAbilityContext and ExtensionContext are supported. UIAbilityContext is used to check whether the current app is running in the foreground. | |
taskId | string | Yes | ID of the download task. |
Returns:
Type | Description |
|---|---|
API call result code. |
Error codes:
For details about the error codes, please refer to ArkTS API Error Codes.
Error Code | Error Message |
|---|---|
401 | Parameter error. |
1006500007 | The specified service extension connect failed. |
1006500008 | Write param into container failed. |
1006500009 | Request to service error. |
1006500010 | Response from service cannot be recognized. |
Example:
import { moduleInstallManager } from '@kit.StoreKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import type { common } from '@kit.AbilityKit';
try {
// taskId is a field in ModuleInstallSessionState returned by fetchModules.
const taskId: string = '********';
const context = getContext(this) as common.UIAbilityContext;
const rtnCode: moduleInstallManager.ReturnCode =
moduleInstallManager.showCellularDataConfirmation(context, taskId);
hilog.info(0, 'TAG', "Succeeded in getting result:" + rtnCode);
} catch (error) {
hilog.error(0, 'TAG', `showCellularDataConfirmation onError.code is ${error.code}, message is ${error.message}`);
} on(type: 'moduleInstallStatus', callback: Callback<ModuleInstallSessionState>, timeout: number): void
Monitors the progress of the current app download task. Multi-threaded calls are not supported. When a module is loaded, the callback function is used to notify the caller.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Parameters:
Parameter | Type | Mandatory | Description |
|---|---|---|---|
type | string | Yes | The value is always moduleInstallStatus. |
callback | Callback<ModuleInstallSessionState> | Yes | Callback function used to return the result. |
timeout | number | Yes | Maximum listening duration supported by the registered listener. The default duration is 30 minutes (30 x 60s). If the value exceeds 30 minutes, it is considered as 30 minutes. |
Error codes:
For details about the error codes, please refer to ArkTS API Error Codes.
Error Code | Error Message |
|---|---|
401 | Parameter error. |
1006500002 | The interface is called repeatedly with the same input. |
1006500004 | SA connection failed. |
Example:
import { moduleInstallManager } from '@kit.StoreKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
try {
const timeout = 30 * 60;
moduleInstallManager.on('moduleInstallStatus', (data: moduleInstallManager.ModuleInstallSessionState) => {
// Register a listener.
hilog.info(0, 'TAG', 'Succeeded in getting moduleInstallManager.on.' );
}, timeout)
} catch (error) {
hilog.error(0, 'TAG', `moduleInstallManager.on onError.code is ${error.code}, message is ${error.message}`);
} off(type: 'moduleInstallStatus', callback?: Callback<ModuleInstallSessionState>): void
Cancels the monitoring of the current app download task's progress. Multi-threaded calls are not supported.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall
Start version: 4.1.0(11)
Parameters:
Parameter | Type | Mandatory | Description |
|---|---|---|---|
type | string | Yes | The value is always moduleInstallStatus. |
callback | Callback<ModuleInstallSessionState> | No | Callback function used to return the result. If this parameter is left empty, all listeners of the current app will be canceled. |
Error codes:
For details about the error codes, please refer to ArkTS API Error Codes.
Error Code | Error Message |
|---|---|
401 | Parameter error. |
1006500004 | SA connection failed. |
1006500006 | The interface is not used together with "on". |
Example:
import { moduleInstallManager } from '@kit.StoreKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
try {
moduleInstallManager.off('moduleInstallStatus', (data: moduleInstallManager.ModuleInstallSessionState) => {
// Cancel the listener.
hilog.info(0, 'TAG', 'Succeeded in getting moduleInstallManager.off.' );
})
} catch (error) {
hilog.error(0, 'TAG', `moduleInstallManager.off onError.code is ${error.code}, message is ${error.message}`);
}