Developing User-Agent

User-Agent (UA) is a special string that contains key information such as the device type, operating system, and version. In web development, UA is used by the server to identify the source device of the request and its features, so that the server can provide custom content and services. If UAs cannot be correctly identified on a page, multiple exceptions may occur. For example, a page layout optimized for a mobile device may be displayed in disorder on a desktop device, and vice versa. In addition, some browser functionalities or CSS attributes are supported only in specific browser versions. If a page cannot successfully identify the UA, rendering problems or logic errors may occur.

Default User-Agent Structure

• String format

  Mozilla/5.0 ({DeviceType}; {OSName} {OSVersion}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/{ChromeCompatibleVersion}.0.0.0 Safari/537.36 ArkWeb/{ArkWeb VersionCode} {DeviceCompat} {Extension}
  

• Example

  Mozilla/5.0 (Phone; OpenHarmony 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36  ArkWeb/4.1.6.1 Mobile
  

• Fields

  Field	Description
  DeviceType	Device type. The value can be: - Phone - Tablet - PC (2-in-1 device)
  OSName	OS name. Default value: OpenHarmony
  OSVersion	OS version. The value is a two-digit number, in M.S format. You can obtain the value by extracting the first two digits of the version number from the system parameter const.ohos.fullname. Default value: 5.0
  ChromeCompatibleVersion	The version that is compatible with the main Chrome version. The earliest version is 114. Default value: 114
  ArkWeb	Web kernel name of the OpenHarmony version. Default value: ArkWeb
  ArkWeb VersionCode	ArkWeb version number, in the format of a.b.c.d. Default value: 4.1.6.1
  DeviceCompat	Forward compatibility settings. Default value: Mobile
  Extension	Field that can be extended by a third-party application. When a third-party application uses the Web component, UA can be extended. For example, an application information identifier can be added.

NOTE

• Currently, there are two spaces before the ArkWeb field of the default User-Agent.

• Currently, the viewport parameter of the meta tag on the frontend HTML page is enabled or disabled based on whether User-Agent contains the Mobile field. If User-Agent does not contain the Mobile field, the viewport attribute in the meta tag is disabled by default. In this case, you can explicitly set metaViewport to true to enable the viewport attribute.

• You are advised to use the OpenHarmony keyword to identify whether a device is an OpenHarmony device, and use the DeviceType keyword to identify the device type for page display on different devices. (The ArkWeb keyword indicates the web kernel of the device, and the OpenHarmony keyword indicates the operating system of the device.)

• The {DistributionOSName} and {DistributionOSVersion} fields are not supported in versions earlier than API version 15. Since API version 15, they are not displayed in the default User-Agent.

Custom User-Agent Structure

In the following example, getUserAgent() is used to obtain the default User-Agent string, which you can modify or extend as needed.

import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Button('getUserAgent')
        .onClick(() => {
          try {
            let userAgent = this.controller.getUserAgent();
            console.info('userAgent: ' + userAgent);
          } catch (error) {
            console.error(
              `ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

In the following example, setCustomUserAgent() is used to set a custom user agent, which overwrites the default user agent. Therefore, you are advised to add the extension field to the end of the default user agent. For example, to develop a third-party application, you can add a specific application identifier while maintaining the original user agent information.

When src of the Web component is set to a URL, set User-Agent in onControllerAttached. For details, see the following example. Avoid setting the user agent in onLoadIntercept. Otherwise, the setting may fail occasionally. If User-Agent is not set in onControllerAttached, calling setCustomUserAgent may cause mismatches between the loaded page and the intended user agent.

When src of the Web component is set to an empty string, call setCustomUserAgent to set User-Agent and then use loadUrl to load a specific page.

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: 'www.example.com', controller: this.controller })
        .onControllerAttached(() => {
          console.info('onControllerAttached');
          try {
            let userAgent = this.controller.getUserAgent() + this.customUserAgent;
            this.controller.setCustomUserAgent(userAgent);
          } catch (error) {
            console.error(
              `ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
    }
  }
}

Since API version 20, you can use the setAppCustomUserAgent() API to set an application-level custom user agent or use the setUserAgentForHosts() API to set an application-level custom user agent for a specific website. The custom user agent overwrites the system user agent and takes effect for all Web components in the application.

It is recommended that you call the static API getDefaultUserAgent to obtain the default User-Agent string, then call setAppCustomUserAgent and setUserAgentForHosts to set the User-Agent, and then create a Web component with the specified src or load a specific page using loadUrl.

import { webview } from '@kit.ArkWeb';    
import { BusinessError } from '@kit.BasicServicesKit';    

@Entry    
@Component    
struct WebComponent {    
  controller: webview.WebviewController = new webview.WebviewController();    

  aboutToAppear(): void {    
    try {    
      webview.WebviewController.initializeWebEngine();    
      let defaultUserAgent = webview.WebviewController.getDefaultUserAgent();    
      let appUA = defaultUserAgent + ' appUA';    
      webview.WebviewController.setAppCustomUserAgent(appUA);    
      webview.WebviewController.setUserAgentForHosts(    
        appUA,    
        [    
          'www.example.com',    
          'www.baidu.com'    
        ]    
      );    
    } catch (error) {    
      console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);    
    }    
  }    

  build() {    
    Column() {    
      Web({ src: 'www.example.com', controller: this.controller })    
    }    
  }    
}

In the following example, getCustomUserAgent() is used to obtain the custom user agent.

import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  @State userAgent: string = '';

  build() {
    Column() {
      Button('getCustomUserAgent')
        .onClick(() => {
          try {
            this.userAgent = this.controller.getCustomUserAgent();
            console.info('userAgent: ' + this.userAgent);
          } catch (error) {
            console.error(
              `ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
          }
        })
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

User-Agent API Priority

FAQs

How do I use User-Agent to identify different OpenHarmony devices?

OpenHarmony devices can be identified based on the OS name, OS version, and device type in User-Agent. You are advised to check all of them to ensure accurate device identification.

1. Identification based on the OS name

   Use the {OSName} field.

   const isOpenHarmony = () => /OpenHarmony/i.test(navigator.userAgent);   
   

2. Identification based on the OS version

   Use the {OSName} and {OSVersion} fields. The format is OpenHarmony + Version number.

   const matches = navigator.userAgent.match(/OpenHarmony (\d+\.?\d*)/);  
   matches?.length && Number(matches[1]) > 0;  
   

3. Identification based on the device type

   Use the deviceType field.

   // Check whether the device is a mobile phone.
   const isPhone = () => /Phone/i.test(navigator.userAgent);
   
   // Check whether the device is a tablet. 
   const isTablet = () => /Tablet/i.test(navigator.userAgent);
   
   // Check whether the device is a 2-in-1 device. 
   const is2in1 = () => /PC/i.test(navigator.userAgent);
   

How do I simulate the User-Agent of OpenHarmony for frontend debugging?

In Windows, macOS, and Linux, you can use the User-Agent rewriting capability provided by DevTools to simulate the OpenHarmony User-Agent in Chrome, Edge, and Firefox.

How do I customize the User-Agent in OpenHarmony to implement HTML5 compatibility?

OpenHarmony provides the setCustomUserAgent API to customize the User-Agent. To adapt to the UA identifier detection (such as Mobile and OpenHarmony) that mobile HTML5 pages usually depend on and ensure that the default UA information is not overwritten, you are advised to perform the following operations: First, obtain the default User-Agent string through the getDefaultUserAgent API. Then, append the custom identifier field required for HTML5 compatibility to the end of the string. Finally, call the setCustomUserAgent API to set the complete UA string.

How to solve the UA compatibility problem of HTML5 pages?

Q: Why the web page on a mobile device is displayed in the PC style or the web page on a PC is displayed in the mobile style?

A: The website displays different styles of pages based on different UAs. For mobile devices, set DeviceCompat to Mobile and DeviceType to Phone. For PCs, set DeviceCompat to "" and DeviceType to PC. For tablets, set DeviceCompat to "" and DeviceType to Tablet.

Q: Why can't I open some web pages or the message "Unsupported browser" is displayed?

A: The web page is not adapted to the OpenHarmony UA. It is necessary for the web page to perform compatibility processing for the OpenHarmony identifier.

Q: Why does the page redirect in a loop?

A: The application sets conflicting UA identifiers for the two pages that redirect to each other. As a result, the redirection logic on the server enters an infinite loop. Ensure that the application maintains consistent logic when calling setUserAgentForHosts to configure a compatible UA for associated websites, so as to avoid infinite loops in web page redirection logic caused by UA differences.

Q: Why the download link provided by the web page does not match the device platform? For example, the download package for an OpenHarmony device is an APK.

A: The compatibility field in the UA interferes with the server identification. To ensure web page compatibility, some browsers may add non-OpenHarmony operating system names to User-Agent. If the parsing logic sequence of the server is improper, the actual device identifier may be ignored. In this case, you are advised to place the OpenHarmony processing logic before the processing logic of other operating systems.