DEV Community

Cover image for UserAgent Development guidance
liu yang
liu yang

Posted on

UserAgent Development guidance

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}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 to true.
  • 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. The ArkWeb keyword indicates the web kernel used by the device, while the OpenHarmony keyword indicates the operating system. Therefore, it is recommended to identify HarmonyOS devices using the OpenHarmony 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 })
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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}`);
          }
        })
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Top comments (0)