UserAgent (UA) in HarmonyOS Next: Structure, Customization, and Best Practices
Overview
The UserAgent (UA) is a special string that contains critical information such as device type, operating system, and version. If a webpage fails to correctly identify the UA, it may lead to various issues, including layout errors, rendering problems, and logical errors.
Default UserAgent Structure
The default UserAgent is defined as follows:
Mozilla/5.0 ({DeviceType}; {OSName} {OSVersion}; {DistributionOSName} {DistributionOSVersion}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/{ChromeCompatibleVersion}.0.0.0 Safari/537.36 ArkWeb/{ArkWeb VersionCode} {DeviceCompat} {Extension Area}
Example
Mozilla/5.0 (Phone; OpenHarmony 5.0; HarmonyOS 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 ArkWeb/4.1.6.1 Mobile
Field Descriptions
Field | Meaning |
---|---|
DeviceType | The current device type. Values: - Phone: Mobile device - Tablet: Tablet device - PC: 2in1 device |
OSName | The base operating system name. Default: OpenHarmony |
OSVersion | The base operating system version, in the format M.S. Default: For example, 5.0 |
DistributionOSName | The distribution operating system name. Default: HarmonyOS |
DistributionOSVersion | The distribution operating system version, in the format M.S. Default: For example, 5.0 |
ChromeCompatibleVersion | The Chrome-compatible major version number, evolving from version 114. Default: 114 |
ArkWeb | The HarmonyOS Web kernel name. Default: ArkWeb |
ArkWeb VersionCode | The ArkWeb version number, in the format a.b.c.d. Default: For example, 4.1.6.1 |
DeviceCompat | Forward compatibility field. Default: Mobile |
Extension Area | An area for third-party applications to extend the UA string. |
Notes
- The presence of the "Mobile" field in the UserAgent is currently used to determine whether to enable the viewport property in the meta tag of the frontend HTML page. If the "Mobile" field is absent, the viewport property is disabled by default. This can be overridden by explicitly setting the
metaViewport
property totrue
. - It is recommended to identify HarmonyOS devices using the "OpenHarmony" keyword and to recognize device types using the
DeviceType
field for different device-specific page displays. TheArkWeb
keyword indicates the web kernel used by the device, while theOpenHarmony
keyword indicates the operating system. Therefore, it is recommended to identify HarmonyOS devices using theOpenHarmony
keyword.
Customizing the UserAgent
Getting the Default UserAgent
The following example demonstrates how to obtain the default UserAgent using the getUserAgent()
interface, which allows developers to customize the UserAgent based on the default value.
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Button('Get UserAgent')
.onClick(() => {
try {
let userAgent = this.controller.getUserAgent();
console.log("UserAgent: " + userAgent);
} catch (error) {
console.error(`Error Code: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
Web({ src: 'https://www.example.com', controller: this.controller })
}
}
}
Setting a Custom UserAgent
The following example demonstrates how to set a custom UserAgent using the setCustomUserAgent()
interface, which overrides the system's default UserAgent. It is recommended to append custom fields to the end of the default UserAgent string.
When the src
attribute of the Web component is set to a URL, it is recommended to set the UserAgent in the onControllerAttached
callback event, as shown in the example. Failing to do so may result in discrepancies between the loaded page and the actual UserAgent settings.
When the src
attribute of the Web component is set to an empty string, it is recommended to first call the setCustomUserAgent
method to set the UserAgent, and then load the specific page using loadUrl
.
// xxx.ets
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();
// Third-party application information identifier
@State customUserAgent: string = ' DemoApp';
build() {
Column() {
Web({ src: 'https://www.example.com', controller: this.controller })
.onControllerAttached(() => {
console.log("Controller Attached");
try {
let userAgent = this.controller.getUserAgent() + this.customUserAgent;
this.controller.setCustomUserAgent(userAgent);
} catch (error) {
console.error(`Error Code: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
})
}
}
}
Top comments (0)