1# @ohos.bundle.installer (installer) 2 3The **bundle.installer** module provides APIs for you to install, uninstall, and recover bundles on devices. 4 5> **NOTE** 6> 7> 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. 8 9## Modules to Import 10 11```js 12import installer from '@ohos.bundle.installer'; 13``` 14 15## Required Permissions 16 17| Permission | Permission Level | Description | 18| ------------------------------ | ----------- | ---------------- | 19| ohos.permission.INSTALL_BUNDLE | system_core | Permission to install or uninstall bundles.| 20 21For details, see [Permission Levels](../../security/accesstoken-overview.md#permission-levels). 22 23## BundleInstaller.getBundleInstaller 24 25getBundleInstaller(callback: AsyncCallback\<BundleInstaller>): void; 26 27Obtains a **BundleInstaller** object. This API uses an asynchronous callback to return the result. 28 29**System API**: This is a system API and cannot be called by third-party applications. 30 31**System capability**: SystemCapability.BundleManager.BundleFramework.Core 32 33**Parameters** 34 35| Name | Type | Mandatory| Description | 36| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 37| callback | AsyncCallback\<[BundleInstaller](js-apis-installer.md#BundleInstaller)> | Yes | Callback used to return the result. If the operation is successful, **err** is undefined and **data** is the **BundleInstaller** object obtained; otherwise, **err** is an error object.| 38 39**Example** 40 41```ts 42import installer from '@ohos.bundle.installer'; 43 44try { 45 installer.getBundleInstaller((err, data) => { 46 if (err) { 47 console.error('getBundleInstaller failed:' + err.message); 48 } else { 49 console.info('getBundleInstaller successfully'); 50 } 51 }); 52} catch (error) { 53 console.error('getBundleInstaller failed:' + error.message); 54} 55``` 56 57## BundleInstaller.getBundleInstaller 58 59getBundleInstaller(): Promise\<BundleInstaller>; 60 61Obtains a **BundleInstaller** object. This API uses an asynchronous callback to return the result. 62 63**System API**: This is a system API and cannot be called by third-party applications. 64 65**System capability**: SystemCapability.BundleManager.BundleFramework.Core 66 67**Return value** 68| Type | Description | 69| ------------------------------------------------------------ | ------------------------------------ | 70| Promise\<[BundleInstaller](js-apis-installer.md#BundleInstaller)> | Promise used to return the **BundleInstaller** object obtained.| 71 72**Example** 73 74```ts 75import installer from '@ohos.bundle.installer'; 76 77try { 78 installer.getBundleInstaller().then((data) => { 79 console.info('getBundleInstaller successfully.'); 80 }).catch((error) => { 81 console.error('getBundleInstaller failed. Cause: ' + error.message); 82 }); 83} catch (error) { 84 console.error('getBundleInstaller failed. Cause: ' + error.message); 85} 86``` 87 88## BundleInstaller.install 89install(hapFilePaths: Array<string>, installParam: InstallParam, callback: AsyncCallback<void>): void; 90 91Installs a bundle. This API uses an asynchronous callback to return the result. 92 93**System API**: This is a system API and cannot be called by third-party applications. 94 95**Required permissions**: ohos.permission.INSTALL_BUNDLE 96 97**System capability**: SystemCapability.BundleManager.BundleFramework.Core 98 99**Parameters** 100 101| Name | Type | Mandatory| Description | 102| --------------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 103| hapFilePaths | Array<string> | Yes | Paths where the HAP files of the bundle are stored, which are the data directories. If only one directory is passed, the HAP files in the directory must belong to the same bundle and have the same signature.| 104| installParam | [InstallParam](#installparam) | Yes | Parameters required for the installation. | 105| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is undefined; otherwise, **err** is an error object.| 106 107**Error codes** 108 109For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md). 110 111| ID| Error Message | 112| -------- | ------------------------------------------------------------ | 113| 17700004 | The specified user ID is not found. | 114| 17700010 | Failed to install the HAP because the HAP fails to be parsed. | 115| 17700011 | Failed to install the HAP because the HAP signature fails to be verified. | 116| 17700012 | Failed to install the HAP because the HAP path is invalid or the HAP is too large. | 117| 17700015 | Failed to install the HAPs because they have different configuration information. | 118| 17700016 | Failed to install the HAP because of insufficient system disk space. | 119| 17700017 | Failed to install the HAP since the version of the HAP to install is too early. | 120| 17700018 | Failed to install because the dependent module does not exist. | 121 122**Example** 123 124```ts 125import installer from '@ohos.bundle.installer'; 126let hapFilePaths = ['/data/storage/el2/base/haps/entry/files/']; 127let installParam = { 128 userId: 100, 129 isKeepData: false, 130 installFlag: 1, 131}; 132 133try { 134 installer.getBundleInstaller().then(data => { 135 data.install(hapFilePaths, installParam, err => { 136 if (err) { 137 console.error('install failed:' + err.message); 138 } else { 139 console.info('install successfully.'); 140 } 141 }); 142 }).catch(error => { 143 console.error('getBundleInstaller failed. Cause: ' + error.message); 144 }); 145} catch (error) { 146 console.error('getBundleInstaller failed. Cause: ' + error.message); 147} 148``` 149 150## BundleInstaller.uninstall 151 152uninstall(bundleName: string, installParam: InstallParam, callback: AsyncCallback<void>): void; 153 154Uninstalls a bundle. This API uses an asynchronous callback to return the result. 155 156**System API**: This is a system API and cannot be called by third-party applications. 157 158**Required permissions**: ohos.permission.INSTALL_BUNDLE 159 160**System capability**: SystemCapability.BundleManager.BundleFramework.Core 161 162**Parameters** 163 164| Name | Type | Mandatory| Description | 165| ---------- | ---------------------------------------------------- | ---- | ---------------------------------------------- | 166| bundleName | string | Yes | Name of the target bundle. | 167| installParam | [InstallParam](#installparam) | Yes | Parameters required for the uninstall. | 168| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is undefined; otherwise, **err** is an error object.| 169 170**Error codes** 171 172For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md). 173 174| ID| Error Message | 175| -------- | ------------------------------------------------------------ | 176| 17700004 | The specified user ID is not found. | 177| 17700020 | The specified bundle is pre-installed bundle which cannot be uninstalled. | 178 179**Example** 180 181```ts 182import installer from '@ohos.bundle.installer'; 183let bundleName = 'com.ohos.demo'; 184let installParam = { 185 userId: 100, 186 isKeepData: false, 187 installFlag: 1 188}; 189 190try { 191 installer.getBundleInstaller().then(data => { 192 data.uninstall(bundleName, installParam, err => { 193 if (err) { 194 console.error('uninstall failed:' + err.message); 195 } else { 196 console.info('uninstall successfully.'); 197 } 198 }); 199 }).catch(error => { 200 console.error('getBundleInstaller failed. Cause: ' + error.message); 201 }); 202} catch (error) { 203 console.error('getBundleInstaller failed. Cause: ' + error.message); 204} 205``` 206 207## BundleInstaller.recover 208 209recover(bundleName: string, installParam: InstallParam, callback: AsyncCallback<void>): void; 210 211Recovers a bundle. This API uses an asynchronous callback to return the result. 212 213**System API**: This is a system API and cannot be called by third-party applications. 214 215**Required permissions**: ohos.permission.INSTALL_BUNDLE 216 217**System capability**: SystemCapability.BundleManager.BundleFramework.Core 218 219**Parameters** 220 221| Name | Type | Mandatory| Description | 222| ---------- | ---------------------------------------------------- | ---- | ---------------------------------------------- | 223| bundleName | string | Yes | Name of the target bundle. | 224| installParam | [InstallParam](#installparam) | Yes | Parameters required for the recovering. | 225| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is undefined; otherwise, **err** is an error object.| 226 227**Error codes** 228 229For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md). 230 231| ID| Error Message | 232| -------- | ----------------------------------- | 233| 17700004 | The specified user ID is not found. | 234 235**Example** 236 237```ts 238import installer from '@ohos.bundle.installer'; 239let bundleName = 'com.ohos.demo'; 240let installParam = { 241 userId: 100, 242 isKeepData: false, 243 installFlag: 1 244}; 245 246try { 247 installer.getBundleInstaller().then(data => { 248 data.recover(bundleName, installParam, err => { 249 if (err) { 250 console.error('recover failed:' + err.message); 251 } else { 252 console.info('recover successfully.'); 253 } 254 }); 255 }).catch(error => { 256 console.error('getBundleInstaller failed. Cause: ' + error.message); 257 }); 258} catch (error) { 259 console.error('getBundleInstaller failed. Cause: ' + error.message); 260} 261``` 262 263## HashParam 264 265Defines the hash parameters for bundle installation and uninstall. 266 267 **System capability**: SystemCapability.BundleManager.BundleFramework.Core 268 269 **System API**: This is a system API and cannot be called by third-party applications. 270 271| Name | Type | Mandatory| Description | 272| ---------- | ------ | ---------------- | ---------------- | 273| moduleName | string | Yes| Module name of the bundle.| 274| hashValue | string | Yes| Hash value. | 275 276## InstallParam 277 278Defines the parameters that need to be specified for bundle installation, uninstall, or recovering. 279 280 **System capability**: SystemCapability.BundleManager.BundleFramework.Core 281 282 **System API**: This is a system API and cannot be called by third-party applications. 283 284| Name | Type | Mandatory | Description | 285| ------------------------------ | ------------------------------ | ------------------ | ------------------ | 286| userId | number | No | User ID. You can use [queryOsAccountLocalIdFromProcess](js-apis-osAccount.md#getOsAccountLocalId) to obtain the user of the current process.| 287| installFlag | number | No | Installation flag. The value **0** means initial installation and **1** means overwrite installation.| 288| isKeepData | boolean | No | Whether to retain the data directory during bundle uninstall.| 289| hashParams | Array<[HashParam](#hashparam)> | No| Hash parameters. | 290| crowdtestDeadline| number | No |End date of crowdtesting.| 291