目录

moduleInstallManager (On-Demand Feature Distribution)

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 Import

import { moduleInstallManager } from '@kit.StoreKit';

InstalledModule

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

bundleManager.ModuleType

Yes

Yes

Module type.

NOTE:

When the value of installStatus is 1, moduleType will return 0 by default, indicating an unknown type.

installStatus

InstallStatus

Yes

No

Module installation result.

ModuleInstallSessionState

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

RequestErrorCode

Yes

No

API call result code.

taskStatus

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.

InstallStatus

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.

ReturnCode

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.

RequestErrorCode

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.

TaskStatus

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.

moduleInstallManager.getInstalledModule

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

InstalledModule

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}`);
}

InstallProvider

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)

InstallRequest

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)

ModuleInstallProvider

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)

[h2]ModuleInstallProvider.createModuleInstallRequest

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

common.UIAbilityContext | common.ExtensionContext

Yes

Context of the app that calls the API.

Returns:

Type

Description

ModuleInstallRequest

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}`);
}

ModuleInstallRequest

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)

[h2]ModuleInstallRequest.addModule

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

ReturnCode

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}`);
}

moduleInstallManager.fetchModules

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

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}`);
}

moduleInstallManager.cancelTask

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

ReturnCode

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}`);
}

moduleInstallManager.showCellularDataConfirmation

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

common.UIAbilityContext | common.ExtensionContext

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

ReturnCode

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}`);
}

moduleInstallManager.on('moduleInstallStatus')

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}`);
}

moduleInstallManager.off('moduleInstallStatus')

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}`);
}