The API version number format has been adjusted since 26.0.0 (for details, see the version number format adjustment description). This adjustment does not affect the basic logic for determining API compatibility. Therefore, the old version number format is still used in the examples provided in this document.
The relationship between the latest API versions is as follows:
26.0.0 > 6.1.1(24) > 6.1.0(23) > 6.0.2(22) > 6.0.1(21) > 6.0.0(20) > 5.1.1(19) > 5.1.0(18) > 5.0.5(17)
SDK Version Used in Application Development
As mentioned in the introduction, the SDK version used during development determines the scope of API capabilities and specific API behaviors. During development, the following SDK version attributes should be configured.
Attribute | Configuration Item in Source Code (build-profile.json5) | Field in Packaged Application (module.json5) | Description |
|---|---|---|---|
SDK version used for compilation | compileSdkVersion | compileSdkVersion | SDK version used to compile the application project. This field determines the API scope that can be automatically associated during development and the version of the toolchain used. The value defaults to the SDK version bundled with DevEco Studio. If explicitly configured, it must be set to the SDK version currently bundled with DevEco Studio. |
Target SDK version of the application | targetSdkVersion | targetAPIVersion | Target SDK version of the application. The default value is the SDK version used to compile the application, which is the same as the value of compileSdkVersion. For system-side changes involving API version isolation, the application's behavior on the device aligns with the API version defined by its targetSdkVersion. For example, if a device's API version is 5.0.2(14) but an application's targetSdkVersion is 5.0.1(13), the API behavior of version 5.0.1(13) will apply under API version isolation. API changes introduced in 5.0.2(14) will not affect the application's actual behavior on its running device. You are advised to consider the impact of API behavior changes when recompiling the application project after upgrading the SDK, and properly set the targetSdkVersion value. |
Minimum compatible SDK version of the application | compatibleSdkVersion | minAPIVersion | Minimum compatible SDK version of the application. The API version of the device system must not be earlier than this value. Otherwise, installation will fail. The value of this field cannot be later than the target SDK version. Setting compatibleSdkVersion to a lower value allows installation on earlier system versions. However, you have to implement compatibility checks for any APIs unavailable in that minimum compatible SDK version to ensure normal operation. |
In your project configuration, the relationship between these three SDK version attributes must be: compatibleSdkVersion ≤ targetSdkVersion ≤ compileSdkVersion. Configurations violating this rule will trigger an error.
Example
If you use and adapt to API version 6.0.2(22) and want the application to run on as many HarmonyOS devices as possible, you can perform the following configuration in the build-profile.json5 file of the application project:
"products": [
{
"name": "default",
"signingConfig": "default",
"compileSdkVersion": "6.0.2(22)",
"targetSdkVersion": "6.0.2(22)",
"compatibleSdkVersion": "6.0.0(20)",
"runtimeOS": "HarmonyOS",
...
}
] In this example, the compatibleSdkVersion value is set to 6.0.0(20). (Note: The minimum value of compatibleSdkVersion can be determined based on the application operation policy and the API version distribution across the HarmonyOS device landscape.) However, the application is upgraded to 6.0.2(22) and uses the new APIs of this version, which may run abnormally in 6.0.0(20). Therefore, the API version needs to be checked for protection. For details, see API Compatibility Check and Warning Masking.
API Version of the Device System Running the Application
As mentioned in the introduction, whether an application runs normally on a device depends on the compatibility between the SDK version declared in the application and the API version carried by the device system.
You can obtain the API version of the device system (ROM) through any of the following three methods:
- [Method 1]: Go to Settings > About to view the API version.
Note: The API version on this page is derived from the distributionOSApiName and sdkApiVersion properties of deviceInfo.
- [Method 2]: Run the hdc commands.
hdc shell param get const.product.os.dist.apiname hdc shell param get const.product.os.dist.apiversion hdc shell param get const.ohos.apiversion
Where:
- const.product.os.dist.apiname and const.product.os.dist.apiversion represent the first part of the HarmonyOS API version (X.Y.Z in X.Y.Z(N)).
The value of const.product.os.dist.apiname is a string in the format X.Y.Z
The value of const.product.os.dist.apiversion is a numeric value, converted from apiname using the formula: apiversion = X*10000 + Y*100 + Z.
- const.ohos.apiversion is the API level of the OpenHarmony base.
Example:
> hdc shell param get const.product.os.dist.apiname > 5.0.5 > hdc shell param get const.product.os.dist.apiversion > 50005 > hdc shell param get const.ohos.apiversion > 17
- const.product.os.dist.apiname and const.product.os.dist.apiversion represent the first part of the HarmonyOS API version (X.Y.Z in X.Y.Z(N)).
- [Method 3]: Use public APIs. For ArkTS, you can use the distributionOSApiVersion or sdkApiVersion API from deviceInfo. For details, see @ohos.deviceInfo (Device Information).
[h2]SDK Version Information Recorded in the Application Package
The module.json file in the compiled bundle records three fields: compileSdkVersion, targetAPIVersion, and minAPIVersion. Their functions are detailed in the SDK version attribute table above.
After an application project is compiled, the content of the app.json5 and module.json5 files in the project is merged into a single module.json file in the build output of each module. For details, see Application Configuration Files. Therefore, the preceding three version fields are from module.json5 in the project file and from module.json in the build output. Pay attention to the source when obtaining them.
AppGallery primarily uses minAPIVersion to control the distribution scope, as it indicates the minimum API version of devices the application can be distributed to.
If the API version of a user's device is lower than the minAPIVersion specified in the application package, the application can still be displayed on the recommendation page of AppGallery on the device or be found through search. However, when the user attempts to install the application, a message will be displayed indicating that the application cannot be installed and providing the required system version.
[h2]API Version Isolation for Behavioral Changes
API behavioral changes introduced during evolution can directly impact application compatibility, depending on whether the system implements API version isolation for these changes.
Version isolation for API behavioral changes serves as a protective mechanism. By specifying the target runtime version in the application's source code project through the targetSdkVersion field, you instruct the system on which API behavior to apply.
- For APIs with version-isolated behavioral changes, devices running API versions earlier than the change introduction version retain the pre-change API behavior. The new behavior applies only to the version in which the change was introduced and later versions.
For an application using such an API:
- If the configured targetSdkVersion is earlier than the version where the API behavior change was introduced, the application remains unaffected and will run normally on systems with later API versions (ROM API version ≥ the change introduction version).
- If the configured targetSdkVersion is higher than or equal to the version where the API behavior change was introduced, you have to adapt the application accordingly to ensure normal operation on systems with later API versions (ROM API version ≥ the change introduction version).
- For APIs whose behavioral changes lack version isolation, all applications using these APIs will be affected. You must follow the adaptation guidance provided in the change description, re-declare your application's SDK version requirements, complete recompilation, and resubmit to AppGallery. Otherwise, they will be affected by the API behavior change when running on systems with higher SDK versions.
From January 2025 onwards, whether version isolation is applied for API behavioral changes will be explicitly declared.
All applications are required to explicitly configure targetSdkVersion, based on which the system can determine the application's target version and thereby apply the correct behavior for version-isolated APIs. Since API version 6.0.0(20), if you open a project in DevEco Studio where targetSdkVersion is not configured in the source code, a dialog will prompt you to configure it.