65458189创建于 2025年12月26日历史提交

@ohos.app.ability.appManager (appManager) (System API)

The appManager module implements application management. You can use the APIs of this module to query whether the application is undergoing a stability test, whether the application is running on a RAM constrained device, the memory size of the application, and information about the running process.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

This topic describes only system APIs provided by the module. For details about its public APIs, see @ohos.app.ability.appManager (appManager).

Modules to Import

import { appManager } from '@kit.AbilityKit';

appManager.PreloadMode¹²⁺

Enumerates the modes used for preloading an application process.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

Name	Value	Description
PRESS_DOWN	0	The application process is preloaded when the application icon is pressed.

KeepAliveAppType¹⁴⁺

Enumerates the types of applications to be kept alive.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Value	Description
ALL	0	Third-party and system applications. This value can be called only as an input parameter of getKeepAliveBundles.
THIRD_PARTY	1	Third-party application.
SYSTEM	2	System application.

KeepAliveSetter¹⁴⁺

Enumerates the types of parties that set to keep applications alive.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Value	Description
SYSTEM	0	System, which means that the system sets to keep applications alive.
USER	1	User, which means that a user sets to keep applications alive.

KeepAliveBundleInfo¹⁴⁺

Describes the keep-alive application information, which can be obtained by calling getKeepAliveBundles or getKeepAliveAppServiceExtensions.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Name	Type	Read-Only	Optional	Description
bundleName	string	No	No	Bundle name.
type	KeepAliveAppType	No	No	Type of the application to be kept alive.
setter	KeepAliveSetter	No	No	Type of the party that sets to keep the application alive.
setterUserId²⁰⁺	number	No	Yes	ID of the user who keeps the application alive.
allowUserToCancel²⁰⁺	boolean	No	Yes	Whether the user can cancel the keep-alive status. true if yes, false otherwise.

appManager.isSharedBundleRunning¹⁰⁺

isSharedBundleRunning(bundleName: string, versionCode: number): Promise<boolean>

Checks whether the shared library is in use. This API uses a promise to return the result.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name of the shared library.
versionCode	number	Yes	Version number of the shared library.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. true if the shared library is in use, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

const bundleName = "this is a bundleName";
const versionCode = 1;

appManager.isSharedBundleRunning(bundleName, versionCode).then((data) => {
  console.info(`The shared bundle running is: ${JSON.stringify(data)}`);
}).catch((error: BusinessError) => {
  console.error(`error: ${JSON.stringify(error)}`);
});

appManager.isSharedBundleRunning¹⁰⁺

isSharedBundleRunning(bundleName: string, versionCode: number, callback: AsyncCallback<boolean>): void

Checks whether the shared library is in use. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name of the shared library.
versionCode	number	Yes	Version number of the shared library.
callback	AsyncCallback<boolean>>	Yes	Callback used to return the result. true if the shared library is in use, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';

const bundleName = "this is a bundleName";
const versionCode = 1;

appManager.isSharedBundleRunning(bundleName, versionCode, (err, data) => {
  if (err) {
    console.error(`err: ${JSON.stringify(err)}`);
  } else {
    console.info(`The shared bundle running is: ${JSON.stringify(data)}`);
  }
});

appManager.on('appForegroundState')¹¹⁺

on(type: 'appForegroundState', observer: AppForegroundStateObserver): void

Registers an observer to listen for application start or exit events. The observer can be used by a system application to observe the start or event events of all applications.

System API: This is a system API.

Required permissions: ohos.permission.RUNNING_STATE_OBSERVER

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'appForegroundState'.
observer	AppForegroundStateObserver	Yes	Observer used to listen for application start or exit events.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let observer: appManager.AppForegroundStateObserver = {
  onAppStateChanged(appStateData) {
    console.info(`[appManager] onAppStateChanged: ${JSON.stringify(appStateData)}`);
  },
};

try {
  appManager.on('appForegroundState', observer);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.on('abilityFirstFrameState')¹²⁺

on(type: 'abilityFirstFrameState', observer: AbilityFirstFrameStateObserver, bundleName?: string): void

Registers an observer to listen for the complete of the first frame rendering of a given ability.

System API: This is a system API.

Required permissions: ohos.permission.RUNNING_STATE_OBSERVER

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'abilityFirstFrameState'.
observer	AbilityFirstFrameStateObserver	Yes	Observer used to listen for the complete of the first frame rendering of the ability.
bundleName	string	No	Bundle name of the ability to be listened for. If this parameter is left blank, the event is listened for all applications.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let abilityFirstFrameStateObserverForAll: appManager.AbilityFirstFrameStateObserver = {
  onAbilityFirstFrameDrawn(abilityStateData: appManager.AbilityFirstFrameStateData) {
    console.info("abilityFirstFrame: ", JSON.stringify(abilityStateData));
  }
};

try {
  appManager.on('abilityFirstFrameState', abilityFirstFrameStateObserverForAll);
} catch (e) {
  let code = (e as BusinessError).code;
  let message = (e as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.off('appForegroundState')¹¹⁺

off(type: 'appForegroundState', observer?: AppForegroundStateObserver): void

Unregisters the observer used to listen for application start or exit events.

System API: This is a system API.

Required permissions: ohos.permission.RUNNING_STATE_OBSERVER

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'appForegroundState'.
observer	AppForegroundStateObserver	No	Observer used to listen for application start or exit events.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let observer_: appManager.AppForegroundStateObserver | undefined;
// 1. Register an observer to listen for application start or exit events.
let observer: appManager.AppForegroundStateObserver = {
  onAppStateChanged(appStateData: appManager.AppStateData) {
    console.info(`[appManager] onAppStateChanged: ${JSON.stringify(appStateData)}`);
  },
};

try {
  appManager.on('appForegroundState', observer);
  // Save the observer object.
  observer_ = observer;
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

// 2. Deregister the observer.
try {
  appManager.off('appForegroundState',  observer_);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.off('abilityFirstFrameState')¹²⁺

off(type: 'abilityFirstFrameState', observer?: AbilityFirstFrameStateObserver): void

Deregisters the observer used to listen for the complete of the first frame rendering of a given ability.

System API: This is a system API.

Required permissions: ohos.permission.RUNNING_STATE_OBSERVER

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'abilityFirstFrameState'.
observer	AbilityFirstFrameStateObserver	No	Callback used for deregistration. If this parameter is left blank, all subscriptions to the specified event are canceled.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let abilityFirstFrameStateObserverForAll: appManager.AbilityFirstFrameStateObserver = {
  onAbilityFirstFrameDrawn(abilityStateData: appManager.AbilityFirstFrameStateData) {
    console.info("abilityFirstFrame: ", JSON.stringify(abilityStateData));
  }
};

try {
  appManager.on('abilityFirstFrameState', abilityFirstFrameStateObserverForAll);
} catch (e) {
  let code = (e as BusinessError).code;
  let message = (e as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

try {
  appManager.off('abilityFirstFrameState', abilityFirstFrameStateObserverForAll);
} catch (e) {
  let code = (e as BusinessError).code;
  let message = (e as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.on('applicationState')²¹⁺

on(type: 'applicationState', observer: ApplicationStateObserver, filter: AppStateFilter): number

Registers an application state observer, which allows you to filter for specific application lifecycle changes by setting filter criteria.

System API: This is a system API.

Required permissions: ohos.permission.RUNNING_STATE_OBSERVER

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of the API to call. It is fixed at 'applicationState'.
observer	ApplicationStateObserver	Yes	Application state observer, which is used to listen for application lifecycle changes.
filter	AppStateFilter	Yes	Filter for application lifecycle changes.

Return value

Type	Description
number	ID of the observer registered. You can pass this ID to off to unregister the observer.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
16000050	Internal error. Possible causes: 1. Failed to connect to the system service; 2. The system service failed to communicate with dependency module.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let applicationStateObserver: appManager.ApplicationStateObserver = {
  onForegroundApplicationChanged(appStateData: appManager.AppStateData) {
    console.info(`[appManager] onForegroundApplicationChanged: ${JSON.stringify(appStateData)}`);
  },
  onAbilityStateChanged(abilityStateData: appManager.AbilityStateData) {
    console.info(`[appManager] onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`);
  },
  onProcessCreated(processData: appManager.ProcessData) {
    console.info(`[appManager] onProcessCreated: ${JSON.stringify(processData)}`);
  },
  onProcessDied(processData: appManager.ProcessData) {
    console.info(`[appManager] onProcessDied: ${JSON.stringify(processData)}`);
  },
  onProcessStateChanged(processData: appManager.ProcessData) {
    console.info(`[appManager] onProcessStateChanged: ${JSON.stringify(processData)}`);
  },
  onAppStarted(appStateData: appManager.AppStateData) {
    console.info(`[appManager] onAppStarted: ${JSON.stringify(appStateData)}`);
  },
  onAppStopped(appStateData: appManager.AppStateData) {
    console.info(`[appManager] onAppStopped: ${JSON.stringify(appStateData)}`);
  }
};

/* This example uses the filter to listen for the following application callbacks:
 * 1. onAbilityStateChanged, a callback function used to listen for ability components in the creating state.
 * 2. onProcessCreated, a callback function used to listen for processes in the created state.
 */
let appStateFilter: appManager.AppStateFilter = {
    bundleTypes: appManager.FilterBundleType.APP,
    appStateTypes: appManager.FilterAppStateType.CREATE | appManager.FilterAppStateType.FOREGROUND,
    processStateTypes: appManager.FilterProcessStateType.CREATE,
    abilityStateTypes: appManager.FilterAbilityStateType.CREATE,
    callbacks: appManager.FilterCallback.ON_ABILITY_STATE_CHANGED | appManager.FilterCallback.ON_PROCESS_CREATED
};

try {
  const observerId = appManager.on('applicationState', applicationStateObserver, appStateFilter);
  console.info(`[appManager] observerCode: ${observerId}`);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.getForegroundApplications

getForegroundApplications(callback: AsyncCallback<Array<AppStateData>>): void

Obtains applications that are running in the foreground. The application information is defined by AppStateData. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<AppStateData>>	Yes	Callback used to return the API call result and an array holding the application state data. You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

function getForegroundApplicationsCallback(err: BusinessError, data: Array<appManager.AppStateData>) {
  if (err) {
    console.error(`getForegroundApplicationsCallback fail, err: ${JSON.stringify(err)}`);
  } else {
    console.info(`getForegroundApplicationsCallback success, data: ${JSON.stringify(data)}`);
  }
}

try {
  appManager.getForegroundApplications(getForegroundApplicationsCallback);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.getForegroundApplications

getForegroundApplications(): Promise<Array<AppStateData>>

Obtains applications that are running in the foreground. The application information is defined by AppStateData. This API uses a promise to return the result.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Return value

Type	Description
Promise<Array<AppStateData>>	Promise used to return an array holding the application state data.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

appManager.getForegroundApplications().then((data) => {
  console.info(`getForegroundApplications success, data: ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`getForegroundApplications fail, err: ${JSON.stringify(err)}`);
});

appManager.killProcessWithAccount

killProcessWithAccount(bundleName: string, accountId: number): Promise<void>

Kills a process by bundle name and account ID. This API uses a promise to return the result.

NOTE

The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS, ohos.permission.KILL_APP_PROCESSES, or ohos.permission.CLEAN_BACKGROUND_PROCESSES

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
accountId	number	Yes	ID of a system account. For details, see getOsAccountLocalId.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = 'bundleName';
let accountId = 0;

try {
  appManager.killProcessWithAccount(bundleName, accountId).then(() => {
    console.info('killProcessWithAccount success');
  }).catch((err: BusinessError) => {
    console.error(`killProcessWithAccount fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.killProcessWithAccount¹⁴⁺

killProcessWithAccount(bundleName: string, accountId: number, clearPageStack: boolean, appIndex?: number): Promise<void>

Kills a process by bundle name and account ID. This API uses a promise to return the result.

NOTE

The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.CLEAN_BACKGROUND_PROCESSES

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
accountId	number	Yes	ID of a system account. For details, see getOsAccountLocalId.
clearPageStack	boolean	Yes	Whether to clear the page stack. true to clear, false otherwise.
appIndex	number	No	Index of an application clone.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	If the input parameter is not valid parameter.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = 'bundleName';
let accountId = 0;
let isClearPageStack = false;
let appIndex = 1;

try {
  appManager.killProcessWithAccount(bundleName, accountId, isClearPageStack, appIndex).then(() => {
    console.info('killProcessWithAccount success');
  }).catch((err: BusinessError) => {
    console.error(`killProcessWithAccount fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.killProcessWithAccount

killProcessWithAccount(bundleName: string, accountId: number, callback: AsyncCallback<void>): void

Kills a process by bundle name and account ID. This API uses an asynchronous callback to return the result.

NOTE

The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS, ohos.permission.KILL_APP_PROCESSES, or ohos.permission.CLEAN_BACKGROUND_PROCESSES

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
accountId	number	Yes	ID of a system account. For details, see getOsAccountLocalId.
callback	AsyncCallback<void>	Yes	Callback used to return the API call result. You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = 'bundleName';
let accountId = 0;

function killProcessWithAccountCallback(err: BusinessError) {
  if (err) {
    console.error(`killProcessWithAccountCallback fail, err: ${JSON.stringify(err)}`);
  } else {
    console.info('killProcessWithAccountCallback success.');
  }
}

appManager.killProcessWithAccount(bundleName, accountId, killProcessWithAccountCallback);

appManager.killProcessesByBundleName

killProcessesByBundleName(bundleName: string, callback: AsyncCallback<void>)

Kills a process by bundle name. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.KILL_APP_PROCESSES or ohos.permission.CLEAN_BACKGROUND_PROCESSES

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
callback	AsyncCallback<void>	Yes	Callback used to return the API call result. You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = 'bundleName';

function killProcessesByBundleNameCallback(err: BusinessError) {
  if (err) {
    console.error(`killProcessesByBundleNameCallback fail, err: ${JSON.stringify(err)}`);
  } else {
    console.info('killProcessesByBundleNameCallback success.');
  }
}

try {
  appManager.killProcessesByBundleName(bundleName, killProcessesByBundleNameCallback);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.killProcessesByBundleName

killProcessesByBundleName(bundleName: string): Promise<void>

Kills a process by bundle name. This API uses a promise to return the result.

Required permissions: ohos.permission.KILL_APP_PROCESSES or ohos.permission.CLEAN_BACKGROUND_PROCESSES

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = 'bundleName';

try {
  appManager.killProcessesByBundleName(bundleName).then((data) => {
    console.info('killProcessesByBundleName success.');
  }).catch((err: BusinessError) => {
    console.error(`killProcessesByBundleName fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.clearUpApplicationData

clearUpApplicationData(bundleName: string, callback: AsyncCallback<void>): void

Clears application data by bundle name. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.CLEAN_APPLICATION_DATA

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
callback	AsyncCallback<void>	Yes	Callback used to return the API call result. You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = 'bundleName';

function clearUpApplicationDataCallback(err: BusinessError) {
  if (err) {
    console.error(`clearUpApplicationDataCallback fail, err: ${JSON.stringify(err)}`);
  } else {
    console.info('clearUpApplicationDataCallback success.');
  }
}

try {
  appManager.clearUpApplicationData(bundleName, clearUpApplicationDataCallback);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.clearUpApplicationData

clearUpApplicationData(bundleName: string): Promise<void>

Clears application data by bundle name. This API uses a promise to return the result.

Required permissions: ohos.permission.CLEAN_APPLICATION_DATA

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.

Return value

Type	Description
Promise<void>	Promise used to return the API call result. You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = 'bundleName';

try {
  appManager.clearUpApplicationData(bundleName).then((data) => {
    console.info('clearUpApplicationData success.');
  }).catch((err: BusinessError) => {
    console.error(`clearUpApplicationData fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.getProcessMemoryByPid¹⁰⁺

getProcessMemoryByPid(pid: number, callback: AsyncCallback<number>): void

Obtains the memory size of a process. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
pid	number	Yes	Process ID. For details, see getRunningProcessInfoByBundleName.
callback	AsyncCallback<number>	Yes	Callback used to return the API call result and the memory size (in KB). You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let pid = 0;
function getProcessMemoryByPidCallback(err: BusinessError, data: number) {
  if (err) {
    console.error(`getProcessMemoryByPidCallback fail, err: ${JSON.stringify(err)}`);
  } else {
    console.info('getProcessMemoryByPidCallback success.');
  }
}

try {
  appManager.getProcessMemoryByPid(pid, getProcessMemoryByPidCallback);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.getProcessMemoryByPid¹⁰⁺

getProcessMemoryByPid(pid: number): Promise<number>

Obtains the memory size of a process. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
pid	number	Yes	Process ID. For details, see getRunningProcessInfoByBundleName.

Return value

Type	Description
Promise<number>	Promise used to return the API call result and the memory size (in KB). You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let pid = 0;

try {
  appManager.getProcessMemoryByPid(pid).then((data) => {
    console.info('getProcessMemoryByPid success.');
  }).catch((err: BusinessError) => {
    console.error(`getProcessMemoryByPid fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.getRunningProcessInfoByBundleName¹⁰⁺

getRunningProcessInfoByBundleName(bundleName: string, callback: AsyncCallback<Array<ProcessInformation>>): void

Obtains information about the running processes by bundle name. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
callback	AsyncCallback<Array<ProcessInformation>>	Yes	Callback used to return the API call result and the process running information. You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = "bundleName";
function getRunningProcessInfoByBundleNameCallback(err: BusinessError, data: Array<appManager.ProcessInformation>) {
  if (err) {
    console.error(`getRunningProcessInfoByBundleNameCallback fail, err: ${JSON.stringify(err)}`);
  } else {
    console.info('getRunningProcessInfoByBundleNameCallback success.');
  }
}

try {
  appManager.getRunningProcessInfoByBundleName(bundleName, getRunningProcessInfoByBundleNameCallback);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.getRunningProcessInfoByBundleName¹⁰⁺

getRunningProcessInfoByBundleName(bundleName: string): Promise<Array<ProcessInformation>>

Obtains information about the running processes by bundle name. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.

Return value

Type	Description
Promise<Array<ProcessInformation>>	Promise used to return the API call result and the process running information. You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = "bundleName";

try {
  appManager.getRunningProcessInfoByBundleName(bundleName).then((data) => {
    console.info('getRunningProcessInfoByBundleName success.');
  }).catch((err: BusinessError) => {
    console.error(`getRunningProcessInfoByBundleName fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.getRunningProcessInfoByBundleName¹⁰⁺

getRunningProcessInfoByBundleName(bundleName: string, userId: number, callback: AsyncCallback<Array<ProcessInformation>>): void

Obtains information about the running processes by bundle name and user ID. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
userId	number	Yes	User ID.
callback	AsyncCallback<Array<ProcessInformation>>	Yes	Callback used to return the API call result and the process running information. You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = "bundleName";
let userId = 0;
function getRunningProcessInfoByBundleNameCallback(err: BusinessError, data: Array<appManager.ProcessInformation>) {
  if (err) {
    console.error(`getRunningProcessInfoByBundleNameCallback fail, err: ${JSON.stringify(err)}`);
  } else {
    console.info('getRunningProcessInfoByBundleNameCallback success.');
  }
}

try {
  appManager.getRunningProcessInfoByBundleName(bundleName, userId, getRunningProcessInfoByBundleNameCallback);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.getRunningProcessInfoByBundleName¹⁰⁺

getRunningProcessInfoByBundleName(bundleName: string, userId: number): Promise<Array<ProcessInformation>>

Obtains information about the running processes by bundle name and user ID. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
userId	number	Yes	User ID.

Return value

Type	Description
Promise<Array<ProcessInformation>>	Promise used to return the API call result and the process running information. You can perform error handling or custom processing in this callback.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = "bundleName";
let userId = 0;

try {
  appManager.getRunningProcessInfoByBundleName(bundleName, userId).then((data) => {
    console.info('getRunningProcessInfoByBundleName success.');
  }).catch((err: BusinessError) => {
    console.error(`getRunningProcessInfoByBundleName fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.isApplicationRunning¹¹⁺

isApplicationRunning(bundleName: string): Promise<boolean>

Checks whether the application with the specified bundle name is running across all users. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. true is returned if at least one user is running the specified application. false is returned if none of the users are running the application.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = "com.example.myapplication";

appManager.isApplicationRunning(bundleName).then((data) => {
  console.info(`The application running is: ${JSON.stringify(data)}`);
}).catch((error: BusinessError) => {
  console.error(`error: ${JSON.stringify(error)}`);
});

appManager.isApplicationRunning¹¹⁺

isApplicationRunning(bundleName: string, callback: AsyncCallback<boolean>): void

Checks whether the application with the specified bundle name is running across all users. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. true is returned if at least one user is running the specified application. false is returned if none of the users are running the application.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = "com.example.myapplication";

try {
  appManager.isApplicationRunning(bundleName, (err, data) => {
    if (err) {
      console.error(`err: ${JSON.stringify(err)}`);
    } else {
      console.info(`The application running is: ${JSON.stringify(data)}`);
    }
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

ApplicationState

Enumerates the application states. This enum can be used together with AbilityStateData to return the application state.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Name	Value	Description
STATE_CREATE	0	The application is being created.
STATE_FOREGROUND	2	The application is running in the foreground.
STATE_ACTIVE	3	The application is active.
STATE_BACKGROUND	4	The application is running in the background.
STATE_DESTROY	5	The application is being destroyed.

appManager.getRunningProcessInformationByBundleType¹²⁺

getRunningProcessInformationByBundleType(bundleType: bundleManager.BundleType): Promise<Array<ProcessInformation>>

Obtains the information about the running process based on the bundle type. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
bundleType	bundleManager.BundleType	Yes	Bundle type.

Return value

Type	Description
Promise<Array<ProcessInformation>>	Promise used to return the process information.

Error codes For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager, bundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  appManager.getRunningProcessInformationByBundleType(bundleManager.BundleType.ATOMIC_SERVICE)
    .then((data) => {
      console.info(`The running process information is: ${JSON.stringify(data)}`);
    }).catch((error: BusinessError) => {
    console.error(`error: ${JSON.stringify(error)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.preloadApplication¹²⁺

preloadApplication(bundleName: string, userId: number, mode: PreloadMode, appIndex?: number): Promise<void>

Preloads an application process. A successful call does not always mean that the preloading is successful. In other words, the target application process may not be created even if the API is successfully called. This API uses a promise to return the result.

Required permissions: ohos.permission.PRELOAD_APPLICATION

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name of the application to preload.
userId	number	Yes	User ID.
mode	PreloadMode	Yes	Mode used for preloading.
appIndex	number	No	Application index of the twin application to be preloaded.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	Not system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16000050	Internal error.
16300005	The target bundle does not exist.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

try {
  let bundleName = "ohos.samples.etsclock";
  let userId = 100;
  let mode = appManager.PreloadMode.PRESS_DOWN;
  let appIndex = 0;
  appManager.preloadApplication(bundleName, userId, mode, appIndex)
    .then(() => {
      hilog.info(0x0000, 'testTag', `preloadApplication success`);
    })
    .catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', `preloadApplication error, code: ${err.code}, msg:${err.message}`);
    })
} catch (err) {
  hilog.error(0x0000, 'testTag', `preloadApplication error, code: ${(err as BusinessError).code}, msg:${(err as BusinessError).message}`);
}

appManager.getRunningMultiAppInfo¹²⁺

getRunningMultiAppInfo(bundleName: string): Promise<RunningMultiAppInfo>

Obtains the information about running applications in multi-app mode. The multi-app mode means that an application can be simultaneously logged in with different accounts on the same device. This API uses a promise to return the result.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.

Return value

Type	Description
Promise<RunningMultiAppInfo>	Promise used to return the information about running applications with multi-app mode.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16000072	App clone or multi-instance is not supported.
18500001	The bundle does not exist or no patch has been applied.

Example

import { appManager } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let bundleName = "ohos.samples.etsclock";
  appManager.getRunningMultiAppInfo(bundleName).then((info: appManager.RunningMultiAppInfo) => {
      hilog.info(0x0000, 'testTag', `getRunningMultiAppInfo success`);
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', `getRunningMultiAppInfo error, code: ${err.code}, msg:${err.message}`);
    })
} catch (err) {
  hilog.error(0x0000, 'testTag', `getRunningMultiAppInfo error, code: ${err.code}, msg:${err.message}`);
}

appManager.terminateMission¹³⁺

terminateMission(missionId: number): Promise<void>

Terminates a mission. This API uses a promise to return the result.

Required permissions: ohos.permission.KILL_APP_PROCESSES

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
missionId	number	Yes	Mission ID, which can be obtained by calling getMissionInfos.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    Button('start link', { type: ButtonType.Capsule, stateEffect: true })
      .width('87%')
      .height('5%')
      .margin({ bottom: '12vp' })
      .onClick(() => {
        let missionId: number = 0;
        try {
          appManager.terminateMission(missionId).then(()=>{
              console.info('terminateMission success.');
            }).catch((err: BusinessError)=>{
              console.error('terminateMission failed. err: ' + JSON.stringify(err));
            })
        } catch (paramError) {
          let code = (paramError as BusinessError).code;
          let message = (paramError as BusinessError).message;
          console.error(`[appManager] error: ${code}, ${message}`);
        }
      })
  }
}

appManager.getSupportedProcessCachePids¹⁴⁺

getSupportedProcessCachePids(bundleName : string): Promise<Array<number>>

Obtains the PIDs of processes that support quick startup after caching in a specified application. This API uses a promise to return the result.

NOTE

This API can only be used to obtain the PIDs of the system account to which the caller belongs.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.

Return value

Type	Description
Promise<Array<number>>	Promise used to return an array containing the PIDs.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let bundleName = "ohos.samples.processcache";
  appManager.getSupportedProcessCachePids(bundleName).then((pids: Array<number>) => {
      hilog.info(0x0000, 'testTag', `pids: ${JSON.stringify(pids)}`);
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', `get pids error, code: ${err.code}, msg:${err.message}`);
    })
} catch (err) {
  hilog.error(0x0000, 'testTag', `get pids error, code: ${err.code}, msg:${err.message}`);
}

appManager.clearUpAppData¹³⁺

clearUpAppData(bundleName: string, appCloneIndex?: number): Promise<void>

Clears data of a specified application based on the bundle name and application clone index. This API uses a promise to return the result.

Required permissions: ohos.permission.CLEAN_APPLICATION_DATA

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
appCloneIndex	number	No	Index of the application clone.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.
16000073	The app clone index is invalid.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName: string = 'com.ohos.demo';
let appCloneIndex: number = 0;

try {
  appManager.clearUpAppData(bundleName, appCloneIndex).then(() => {
    console.info(`clearUpAppData success.`);
  }).catch((err: BusinessError) => {
    console.error(`clearUpAppData fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] error: ${code}, ${message}`);
}

appManager.setKeepAliveForBundle¹⁴⁺

setKeepAliveForBundle(bundleName: string, userId: number, enable: boolean): Promise<void>

Sets or cancels the keep-alive status for an application that belongs to a specified user. This API uses a promise to return the result.

NOTE

To support keep-alive, mainElement in the module.json5 file of the application must be a UIAbility. The system initiates the keep-alive operation only when this mainElement has been launched.

On 2-in-1 devices, the application must appear in the status bar within 5 seconds of launch. Otherwise, the system revokes the application's keep-alive status and terminate the restarted process.

When the kept-alive application process exits, the system attempts to restart it. If three consecutive restart attempts fail, the system stops restarting the process.

Permission required: ohos.permission.MANAGE_APP_KEEP_ALIVE

System capability: SystemCapability.Ability.AbilityRuntime.Core

Device behavior differences: Starting from API version 18, this API can be properly called only on 2-in-1 devices and wearables. For versions earlier than API version 18, this API can be properly called only on 2-in-1 devices. If it is called on other device types, error code 801 is returned.

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
userId	number	Yes	User ID.
enable	boolean	Yes	Whether to keep the application alive or cancel its keep-alive status. true to keep the application alive, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
16000050	Internal error.
16300005	The target bundle does not exist.
16300008	The target bundle has no MainAbility.
16300009	The target bundle has no status-bar ability.
16300010	The target application is not attached to the status bar.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let bundleName = "ohos.samples.keepaliveapp";
  let userId = 100;
  appManager.setKeepAliveForBundle(bundleName, userId, true).then(() => {
    console.info(`setKeepAliveForBundle success`);
  }).catch((err: BusinessError) => {
    console.error(`setKeepAliveForBundle fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] setKeepAliveForBundle error: ${code}, ${message}`);
}

appManager.getKeepAliveBundles¹⁴⁺

getKeepAliveBundles(type: KeepAliveAppType, userId?: number): Promise<Array<KeepAliveBundleInfo>>

Obtains information about a specified type of keep-alive application of a user. The application information is defined by KeepAliveBundleInfo. This API uses a promise to return the result.

Permission required: ohos.permission.MANAGE_APP_KEEP_ALIVE

System capability: SystemCapability.Ability.AbilityRuntime.Core

Device behavior differences: This API can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code 801 is returned.

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
type	KeepAliveAppType	Yes	Type of the application.
userId	number	No	User ID.

Return value

Type	Description
Promise<Array<KeepAliveBundleInfo>>	Promise used to return the array of keep-alive application information.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let userId = 100;
let type: appManager.KeepAliveAppType = appManager.KeepAliveAppType.THIRD_PARTY;
try {
  appManager.getKeepAliveBundles(type, userId).then((data) => {
    console.info(`getKeepAliveBundles success, data: ${JSON.stringify(data)}`);
  }).catch((err: BusinessError) => {
    console.error(`getKeepAliveBundles fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] getKeepAliveBundles error: ${code}, ${message}`);
}

appManager.killProcessesInBatch¹⁴⁺

killProcessesInBatch(pids: Array<number>): Promise<void>

Kills processes in batches. This API uses a promise to return the result.

Required permissions: ohos.permission.KILL_APP_PROCESSES

System capability: SystemCapability.Ability.AbilityRuntime.Core

Device behavior differences: This API can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code 801 is returned.

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
pids	Array<number>	Yes	Array of process IDs.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let pids: Array<number> = [100, 101, 102];
  appManager.killProcessesInBatch(pids).then(() => {
    console.info(`killProcessesInBatch success`);
  }).catch((err: BusinessError) => {
    console.error(`killProcessesInBatch fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] killProcessesInBatch error: ${code}, ${message}`);
}

appManager.setKeepAliveForAppServiceExtension²⁰⁺

setKeepAliveForAppServiceExtension(bundleName: string, enabled: boolean): Promise<void>

Sets or cancels the keep-alive status for an AppServiceExtensionAbility. This API uses a promise to return the result.

NOTE

This API takes effect only when the application is installed under the user with userId of 1 and the mainElement field in the module.json5 file of the entry HAP is set to AppServiceExtensionAbility.

Permission required: ohos.permission.MANAGE_APP_KEEP_ALIVE

System capability: SystemCapability.Ability.AbilityRuntime.Core

Device behavior differences: This API can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code 801 is returned.

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name.
enabled	boolean	Yes	Whether to keep the application alive or cancel its keep-alive status. true to keep, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
801	Capability not supported.
16000050	Internal error.
16000081	Failed to obtain the target application information.
16000202	Invalid main element type.
16000203	Cannot change the keep-alive status.
16000204	The target bundle is not in u1.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let bundleName = "ohos.samples.keepaliveapp";
  appManager.setKeepAliveForAppServiceExtension(bundleName, true).then(() => {
    console.info(`setKeepAliveForAppServiceExtension success`);
  }).catch((err: BusinessError) => {
    console.error(`setKeepAliveForAppServiceExtension fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] setKeepAliveForAppServiceExtension error: ${code}, ${message}`);
}

appManager.getKeepAliveAppServiceExtensions²⁰⁺

getKeepAliveAppServiceExtensions(): Promise<Array<KeepAliveBundleInfo>>

Obtains information about all AppServiceExtensionAbility components that are kept alive. The information is defined by KeepAliveBundleInfo. This API uses a promise to return the result.

Permission required: ohos.permission.MANAGE_APP_KEEP_ALIVE

System capability: SystemCapability.Ability.AbilityRuntime.Core

Device behavior differences: This API can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code 801 is returned.

System API: This is a system API.

Return value

Type	Description
Promise<Array<KeepAliveBundleInfo>>	Promise used to return the array of keep-alive application information.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
801	Capability not supported.
16000050	Internal error.

Example

import { appManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  appManager.getKeepAliveAppServiceExtensions().then((data) => {
    console.info(`getKeepAliveAppServiceExtensions success, data: ${JSON.stringify(data)}`);
  }).catch((err: BusinessError) => {
    console.error(`getKeepAliveAppServiceExtensions fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`[appManager] getKeepAliveAppServiceExtensions error: ${code}, ${message}`);
}

AppForegroundStateObserver¹¹⁺

type AppForegroundStateObserver = _AppForegroundStateObserver

Defines the listener for the state of application launch and exit.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Type	Description
_AppForegroundStateObserver	Listener for the state of application launch and exit.

AbilityFirstFrameStateObserver¹²⁺

type AbilityFirstFrameStateObserver = _AbilityFirstFrameStateObserver

Defines the listener for the completion of the first frame rendering of the UIAbility.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Type	Description
_AbilityFirstFrameStateObserver	Listener for the completion of the first frame rendering of the UIAbility.

AbilityFirstFrameStateData¹²⁺

type AbilityFirstFrameStateData = _AbilityFirstFrameStateData

Defines the data structure reported when the first frame rendering of the UIAbility is complete.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Type	Description
_AbilityFirstFrameStateData	Data structure reported when the first frame rendering of the UIAbility is complete.

RunningMultiAppInfo¹²⁺

type RunningMultiAppInfo = _RunningMultiAppInfo

Defines the information of an application in multi-app mode in the running state.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Type	Description
_RunningMultiAppInfo	Information of the application in multi-app mode in the running state.

FilterBundleType²¹⁺

Enumerates the types of applications to filter. It can be used with AppStateFilter to filter the application types you want to listen for.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Value	Description
APP	1	Application.
ATOMIC_SERVICE	2	Atomic service.

FilterAppStateType²¹⁺

Enumerates the types of application states to filter. It can be used with AppStateFilter to filter the application state types you want to listen for.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Value	Description
CREATE	1	The application is initializing. It corresponds to the state whose value is 0 in AppStateData.
FOREGROUND	2	The application is running in the foreground. It corresponds to the state whose value is 2 in AppStateData.
BACKGROUND	4	The application is running in the background. It corresponds to the state whose value is 4 in AppStateData.
DESTROY	8	The application has exited. It corresponds to the state whose value is 5 in AppStateData.

FilterProcessStateType²¹⁺

Enumerates the types of process states to filter. It can be used with AppStateFilter to filter the process state types you want to listen for.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Value	Description
CREATE	1	The process has just been created. It corresponds to the state whose value is 0 in ProcessData.
FOREGROUND	2	The process is running in the foreground. It corresponds to the state whose value is 2 in ProcessData.
BACKGROUND	4	The process is running in the background. It corresponds to the state whose value is 4 in ProcessData.
DESTROY	8	The process has terminated. It corresponds to the state whose value is 5 in ProcessData.

FilterAbilityStateType²¹⁺

Enumerates the types of ability states to filter. It can be used with AppStateFilter to filter the ability state types you want to listen for.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Value	Description
CREATE	1	The ability is being created. It corresponds to the state ABILITY_STATE_CREATE in Ability States.
FOREGROUND	2	The ability is running in the foreground. It corresponds to the state ABILITY_STATE_FOREGROUND in Ability States.
BACKGROUND	4	The ability is running in the background. It corresponds to the state ABILITY_STATE_BACKGROUND in Ability States.
DESTROY	8	The ability has been destroyed. It corresponds to the state ABILITY_STATE_TERMINATED in Ability States.

FilterCallback²¹⁺

Enumerates the callbacks to filter. It can be used with AppStateFilter to filter the callbacks you want to listen for.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Value	Description
ON_FOREGROUND_APPLICATION_CHANGED	1	Corresponds to the ApplicationStateObserver.onForegroundApplicationChanged callback, which is executed when the application's foreground/background state changes.
ON_ABILITY_STATE_CHANGED	2	Corresponds to the ApplicationStateObserver.onAbilityStateChanged callback, which is executed when the ability state changes.
ON_PROCESS_CREATED	4	Corresponds to the ApplicationStateObserver.onProcessCreated callback, which is executed when a process is created.
ON_PROCESS_DIED	8	Corresponds to the ApplicationStateObserver.onProcessDied callback, which is executed when a process is destroyed.
ON_PROCESS_STATE_CHANGED	16	Corresponds to the ApplicationStateObserver.onProcessStateChanged callback, which is executed when the process state is updated.
ON_APP_STARTED	32	Corresponds to the ApplicationStateObserver.onAppStarted callback, which is executed when the application's first process is created.
ON_APP_STOPPED	64	Corresponds to the ApplicationStateObserver.onAppStopped callback, which is executed when the application's last process is destroyed.

AppStateFilter²¹⁺

Describes the filter for application lifecycle change events. It can be used as a parameter of on to filter application lifecycle change events you want to listen for.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Name	Type	Read-Only	Optional	Description
bundleTypes	FilterBundleType	No	Yes	Type of application to filter. The options are as follows: - 0: Do not listen for any application type. - A bitwise OR combination of the enumerated values of FilterBundleType, for example, "appManager.FilterBundleType.APP \| appManager.FilterBundleType.ATOMIC_SERVICE" listens for lifecycle change events for both applications and atomic services. - If this parameter is not set, all application types are listened for by default.
appStateTypes	FilterAppStateType	No	Yes	Type of application state to filter. The options are as follows: - 0: Do not listen for any application state. - A bitwise OR combination of the enumerated values of FilterAppStateType, for example, "appManager.FilterAppStateType.CREATE \| appManager.FilterAppStateType.FOREGROUND" listens for both the creating and foreground states of applications. - If this parameter is not set, all application state types are listened for by default.
processStateTypes	FilterProcessStateType	No	Yes	Type of process state to filter. The options are as follows: - 0: Do not listen for any process state. - A bitwise OR combination of the enumerated values of FilterProcessStateType, for example, "appManager.FilterProcessStateType.CREATE \| appManager.FilterProcessStateType.FOREGROUND" listens for both the creating and foreground states of processes. - If this parameter is not set, all process state types are listened for by default.
abilityStateTypes	FilterAbilityStateType	No	Yes	Type of ability state to filter. The options are as follows: - 0: Do not listen for any ability state. - A bitwise OR combination of the enumerated values of FilterAbilityStateType, for example, "appManager.FilterAbilityStateType.CREATE \| appManager.FilterAbilityStateType.FOREGROUND" listens for both the creating and foreground states of ability components. - If this parameter is not set, all ability state types are listened for by default.
callbacks	FilterCallback	No	Yes	Callback to filter. The options are as follows: - 0: Do not listen for any callback. - A bitwise OR combination of the enumerated values of FilterCallback, for example, "appManager.FilterCallback.ON_ABILITY_STATE_CHANGED \| appManager.FilterCallback.ON_PROCESS_STATE_CHANGED" listens for both ApplicationStateObserver.onAbilityStateChanged and ApplicationStateObserver.onProcessStateChanged. - If this parameter is not set, all callbacks enumerated in FilterCallback are listened for by default.

@ohos.app.ability.appManager (appManager) (System API)

Modules to Import

appManager.PreloadMode12+

KeepAliveAppType14+

KeepAliveSetter14+

KeepAliveBundleInfo14+

appManager.isSharedBundleRunning10+

appManager.isSharedBundleRunning10+

appManager.on('appForegroundState')11+

appManager.on('abilityFirstFrameState')12+

appManager.off('appForegroundState')11+

appManager.off('abilityFirstFrameState')12+

appManager.on('applicationState')21+

appManager.getForegroundApplications

appManager.getForegroundApplications

appManager.killProcessWithAccount

appManager.killProcessWithAccount14+

appManager.killProcessWithAccount

appManager.killProcessesByBundleName

appManager.killProcessesByBundleName

appManager.clearUpApplicationData

appManager.clearUpApplicationData

appManager.getProcessMemoryByPid10+

appManager.getProcessMemoryByPid10+

appManager.getRunningProcessInfoByBundleName10+

appManager.getRunningProcessInfoByBundleName10+

appManager.getRunningProcessInfoByBundleName10+

appManager.getRunningProcessInfoByBundleName10+

appManager.isApplicationRunning11+

appManager.isApplicationRunning11+

ApplicationState

appManager.getRunningProcessInformationByBundleType12+

appManager.preloadApplication12+

appManager.getRunningMultiAppInfo12+

appManager.terminateMission13+

appManager.getSupportedProcessCachePids14+

appManager.clearUpAppData13+

appManager.setKeepAliveForBundle14+

appManager.getKeepAliveBundles14+

appManager.killProcessesInBatch14+

appManager.setKeepAliveForAppServiceExtension20+

appManager.getKeepAliveAppServiceExtensions20+

AppForegroundStateObserver11+

AbilityFirstFrameStateObserver12+

AbilityFirstFrameStateData12+

RunningMultiAppInfo12+

FilterBundleType21+

FilterAppStateType21+

FilterProcessStateType21+

FilterAbilityStateType21+

FilterCallback21+

AppStateFilter21+

appManager.PreloadMode¹²⁺

KeepAliveAppType¹⁴⁺

KeepAliveSetter¹⁴⁺

KeepAliveBundleInfo¹⁴⁺

appManager.isSharedBundleRunning¹⁰⁺

appManager.isSharedBundleRunning¹⁰⁺

appManager.on('appForegroundState')¹¹⁺

appManager.on('abilityFirstFrameState')¹²⁺

appManager.off('appForegroundState')¹¹⁺

appManager.off('abilityFirstFrameState')¹²⁺

appManager.on('applicationState')²¹⁺

appManager.killProcessWithAccount¹⁴⁺

appManager.getProcessMemoryByPid¹⁰⁺

appManager.getProcessMemoryByPid¹⁰⁺

appManager.getRunningProcessInfoByBundleName¹⁰⁺

appManager.getRunningProcessInfoByBundleName¹⁰⁺

appManager.getRunningProcessInfoByBundleName¹⁰⁺

appManager.getRunningProcessInfoByBundleName¹⁰⁺

appManager.isApplicationRunning¹¹⁺

appManager.isApplicationRunning¹¹⁺

appManager.getRunningProcessInformationByBundleType¹²⁺

appManager.preloadApplication¹²⁺

appManager.getRunningMultiAppInfo¹²⁺

appManager.terminateMission¹³⁺

appManager.getSupportedProcessCachePids¹⁴⁺

appManager.clearUpAppData¹³⁺

appManager.setKeepAliveForBundle¹⁴⁺

appManager.getKeepAliveBundles¹⁴⁺

appManager.killProcessesInBatch¹⁴⁺

appManager.setKeepAliveForAppServiceExtension²⁰⁺

appManager.getKeepAliveAppServiceExtensions²⁰⁺

AppForegroundStateObserver¹¹⁺

AbilityFirstFrameStateObserver¹²⁺

AbilityFirstFrameStateData¹²⁺

RunningMultiAppInfo¹²⁺

FilterBundleType²¹⁺

FilterAppStateType²¹⁺

FilterProcessStateType²¹⁺

FilterAbilityStateType²¹⁺

FilterCallback²¹⁺

AppStateFilter²¹⁺