Problem Description

A continuous task keeps your process from being suspended while the app sits in the background. It doesn’t wake you up on a schedule. It only keeps you alive, so whatever loop or subscription you started keeps running. The example below uses background location tracking, which is the most common case.

Worth knowing before the code: the type you declare has to match the work you actually do. The system checks this, and if you declare location but never take a fix, it cancels the task within a couple of minutes. So pick the type that describes your real work, not the one that’s easiest to get.

Background Knowledge

A continuous task is requested through backgroundTaskManager.startBackgroundRunning, which takes a UIAbilityContext, an array of mode strings, and a WantAgent. Only a UIAbility can make this request, and it runs in the same process and on the same main thread as the rest of your page. No new process is created, so anything you start before backgrounding stays exactly where it was.

The mode strings come from the set of continuous task types the system defines: location, audioPlayback, audioRecording, dataTransfer, bluetoothInteraction, and others. Each one corresponds to a specific kind of user-perceivable work, and the system performs a consistency check against it. A task requested for one type while a different type of work is being done gets restricted.

Once the task starts, a persistent entry appears in the notification panel. The WantAgent you passed defines what happens when the user taps it. Deleting that notification cancels the task, which is why on('continuousTaskCancel') exists as a way to be told when this happens.

Location itself comes from geoLocationManager in @kit.LocationKit, subscribed through on('locationChange', request, callback) and released with the matching off.

Solution

1. Declare the background mode

In module.json5, add backgroundModes to the ability that will request the task. This has to go on the UIAbility itself, not on an extension, since only a UIAbility can request a continuous task.

"abilities": [
  {
    "name": "EntryAbility",
    "srcEntry": "./ets/entryability/EntryAbility.ets",
    "description": "$string:EntryAbility_desc",
    "icon": "$media:layered_image",
    "label": "$string:EntryAbility_label",
    "backgroundModes": ["location"],
    "startWindowIcon": "$media:startIcon",
    "startWindowBackground": "$color:start_window_background",
    "exported": true,
    "skills": [
      {
        "entities": ["entity.system.home"],
        "actions": ["ohos.want.action.home"]
      }
    ]
  }
]

The value in backgroundModes is specific to your task type. For location tracking it’s “location”, for background audio it’s “audioPlayback”, and so on. Declaring the wrong one, or leaving it out, makes startBackgroundRunning fail.

2. Request the permissions

Still in module.json5, at the module level, not inside the abilities array. Putting it in the wrong place compiles fine but silently registers nothing.

"requestPermissions": [
  { "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" },
  { "name": "ohos.permission.INTERNET" },
  {
    "name": "ohos.permission.APPROXIMATELY_LOCATION",
    "reason": "$string:loc_reason",
    "usedScene": { "abilities": ["EntryAbility"], "when": "always" }
  },
  {
    "name": "ohos.permission.LOCATION",
    "reason": "$string:loc_reason",
    "usedScene": { "abilities": ["EntryAbility"], "when": "always" }
  },
  {
    "name": "ohos.permission.LOCATION_IN_BACKGROUND",
    "reason": "$string:loc_reason",
    "usedScene": { "abilities": ["EntryAbility"], "when": "always" }
  },
  { "name": "ohos.permission.GET_NETWORK_INFO" }
]

KEEP_BACKGROUND_RUNNING is the one that gates the continuous task itself. Without it the request is rejected. The three location permissions are for the tracking work, and INTERNET plus GET_NETWORK_INFO are there because we’re sending data to a server.

Make sure loc_reason actually exists in resources/base/element/string.json. If the string is missing, the permission entry can be dropped without any visible error:

{ "name": "loc_reason", "value": "Required for background location tracking" }3. Ask the user at runtime

Declaring a permission isn’t the same as having it. Location permissions are user-granted, so you have to prompt.

Request the foreground permissions first, then the background one in a separate call. Putting all three in one call tends to fail as a group. You get back authResults full of 2, which means the request was invalid rather than denied, and no dialog ever appears.

private async askPermissions(): Promise<boolean> {
  const mgr = abilityAccessCtrl.createAtManager();

  const fg: Permissions[] = [
    'ohos.permission.APPROXIMATELY_LOCATION',
    'ohos.permission.LOCATION'
  ];
  const r1 = await mgr.requestPermissionsFromUser(this.ctx, fg);
  hilog.info(DOMAIN, TAG, `fg perms=${JSON.stringify(r1.authResults)}`);

  if (!r1.authResults.every((v: number) => v === 0)) {
    this.status = `foreground permission denied: ${JSON.stringify(r1.authResults)}`;
    return false;
  }

  try {
    const r2 = await mgr.requestPermissionsFromUser(
      this.ctx, ['ohos.permission.LOCATION_IN_BACKGROUND']);
    hilog.info(DOMAIN, TAG, `bg perm=${JSON.stringify(r2.authResults)}`);
  } catch (e) {
    hilog.warn(DOMAIN, TAG, `bg perm unavailable ${(e as BusinessError).code}`);
  }

  return true;
}

In authResults, 0 means granted, -1 means denied, and 2 means the request itself was invalid. The background call is wrapped in try/catch because it isn’t available on every device type, wearables in particular. Failing that one isn’t fatal, so we log it and continue.

4. Start the continuous task

This is the core of it. You build a WantAgent, then hand it to startBackgroundRunning along with your context and the list of modes.

private async startTask(): Promise<boolean> {
  const info: wantAgent.WantAgentInfo = {
    wants: [{ bundleName: BUNDLE, abilityName: 'EntryAbility' }],
    actionType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
    actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
  };
  try {
    const agent: WantAgent = await wantAgent.getWantAgent(info);
    const modes: string[] = ['location'];
    const res: backgroundTaskManager.ContinuousTaskNotification =
      await backgroundTaskManager.startBackgroundRunning(this.ctx, modes, agent);
    hilog.info(DOMAIN, TAG, `task started, notificationId=${res.notificationId}`);
    this.status = 'continuous task active';
    return true;
  } catch (e) {
    const err = e as BusinessError;
    hilog.error(DOMAIN, TAG, `start failed ${err.code} ${err.message}`);
    this.status = `start failed ${err.code}: ${err.message}`;
    return false;
  }
}

Three details worth calling out.

The WantAgent describes what happens when the user taps the notification your task creates. Here it opens EntryAbility. That notification is not optional: it appears automatically once the task starts, and if the user swipes it away, the system cancels the task.

The context has to be a UIAbilityContext, which is what getUIContext().getHostContext() returns. Pass the same context to stopBackgroundRunning later.

The modes array has to match what you put in backgroundModes in step 1. A mismatch here is a common reason for the call to fail.

The return value carries the notification id. You don’t have to capture it, and a plain await backgroundTaskManager.startBackgroundRunning(ctx, modes, agent) works just as well. It's useful for two things: confirming in the log that the task really started, and updating the notification content later through Notification Kit.

Stopping is a single call:

async stop(): Promise<void> {
    this.stopTimerAndLocation();
    try {
      await backgroundTaskManager.stopBackgroundRunning(this.ctx);
      hilog.info(DOMAIN, TAG, 'TASK STOPPED');
      this.status = 'durduruldu';
    } catch (e) {
      hilog.error(DOMAIN, TAG, `stop fail ${(e as BusinessError).code}`);
    }
    this.running = false;
  }

5. Start the actual work

The continuous task keeps you alive but does nothing on its own. You still have to start the work, and it has to be the work you declared.

private startLocation(): void {
  if (this.listening) {
    return;
  }
  const req: geoLocationManager.ContinuousLocationRequest = {
    interval: LOCATION_INTERVAL_SEC,
    locationScenario: geoLocationManager.UserActivityScenario.NAVIGATION
  };
  try {
    geoLocationManager.on('locationChange', req, this.onLocation);
    this.listening = true;
    hilog.info(DOMAIN, TAG, 'location subscribed');
  } catch (e) {
    const err = e as BusinessError;
    hilog.error(DOMAIN, TAG, `subscribe failed ${err.code} ${err.message}`);
    this.status = `location error ${err.code}`;
  }
}

private onLocation = (loc: geoLocationManager.Location): void => {
  const t: string = new Date().toTimeString().substring(0, 8);
  hilog.info(DOMAIN, TAG,
    `fix ${t} lat=${loc.latitude.toFixed(5)} lng=${loc.longitude.toFixed(5)}`);
  this.lastFix = `${t}  ${loc.latitude.toFixed(4)}, ${loc.longitude.toFixed(4)}`;
  // send the sample to your backend here
};

THE FULL PAGE

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { wantAgent, WantAgent, abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit';
import { geoLocationManager } from '@kit.LocationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'CT_DEMO';
const DOMAIN: number = 0xF00D;
const BUNDLE: string = 'com.example.myapp';
const LOCATION_INTERVAL_SEC: number = 15;

@Entry
@Component
struct Index {
  @State running: boolean = false;
  @State status: string = 'idle';
  @State lastFix: string = '-';

  private ctx: common.UIAbilityContext =
    this.getUIContext().getHostContext() as common.UIAbilityContext;
  private listening: boolean = false;

  build() {
    Column({ space: 12 }) {
      Text(this.running ? 'TRACKING' : 'STOPPED')
        .fontSize(18)
        .fontColor(this.running ? '#27ae60' : '#888')

      Button(this.running ? 'Stop' : 'Start')
        .width('85%')
        .onClick(() => {
          if (this.running) {
            this.stop();
          } else {
            this.start();
          }
        })

      Text(this.lastFix).fontSize(13).fontColor('#666')
      Text(this.status).fontSize(11).fontColor('#999')
    }
    .width('100%').height('100%').padding(20)
  }

  aboutToAppear(): void {
    try {
      backgroundTaskManager.on('continuousTaskCancel', this.onCancel);
    } catch (e) {
      hilog.error(DOMAIN, TAG, `on cancel failed ${(e as BusinessError).code}`);
    }
  }

  aboutToDisappear(): void {
    try {
      backgroundTaskManager.off('continuousTaskCancel', this.onCancel);
    } catch (e) { /* ignore */ }
    this.stop();
  }

  private onCancel = (info: backgroundTaskManager.ContinuousTaskCancelInfo): void => {
    hilog.warn(DOMAIN, TAG, `task cancelled id=${info.id} reason=${info.reason}`);
    this.status = `cancelled by system, reason=${info.reason}`;
    this.stopLocation();
    this.running = false;
  };

  async start(): Promise<void> {
    if (!geoLocationManager.isLocationEnabled()) {
      this.status = 'location is off in device settings';
      return;
    }

    const granted: boolean = await this.askPermissions();
    if (!granted) {
      return;
    }

    const started: boolean = await this.startTask();
    if (!started) {
      return;
    }

    this.startLocation();
    this.running = true;
  }

  private async askPermissions(): Promise<boolean> {
    const mgr = abilityAccessCtrl.createAtManager();

    const fg: Permissions[] = [
      'ohos.permission.APPROXIMATELY_LOCATION',
      'ohos.permission.LOCATION'
    ];
    const r1 = await mgr.requestPermissionsFromUser(this.ctx, fg);
    hilog.info(DOMAIN, TAG, `fg perms=${JSON.stringify(r1.authResults)}`);

    if (!r1.authResults.every((v: number) => v === 0)) {
      this.status = `foreground permission denied: ${JSON.stringify(r1.authResults)}`;
      return false;
    }

    try {
      const r2 = await mgr.requestPermissionsFromUser(
        this.ctx, ['ohos.permission.LOCATION_IN_BACKGROUND']);
      hilog.info(DOMAIN, TAG, `bg perm=${JSON.stringify(r2.authResults)}`);
    } catch (e) {
      hilog.warn(DOMAIN, TAG, `bg perm unavailable ${(e as BusinessError).code}`);
    }

    return true;
  }

  private async startTask(): Promise<boolean> {
    const info: wantAgent.WantAgentInfo = {
      wants: [{ bundleName: BUNDLE, abilityName: 'EntryAbility' }],
      actionType: wantAgent.OperationType.START_ABILITY,
      requestCode: 0,
      actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
    };
    try {
      const agent: WantAgent = await wantAgent.getWantAgent(info);
      const modes: string[] = ['location'];
      const res: backgroundTaskManager.ContinuousTaskNotification =
        await backgroundTaskManager.startBackgroundRunning(this.ctx, modes, agent);
      hilog.info(DOMAIN, TAG, `task started, notificationId=${res.notificationId}`);
      this.status = 'continuous task active';
      return true;
    } catch (e) {
      const err = e as BusinessError;
      hilog.error(DOMAIN, TAG, `start failed ${err.code} ${err.message}`);
      this.status = `start failed ${err.code}: ${err.message}`;
      return false;
    }
  }

  private startLocation(): void {
    if (this.listening) {
      return;
    }
    const req: geoLocationManager.ContinuousLocationRequest = {
      interval: LOCATION_INTERVAL_SEC,
      locationScenario: geoLocationManager.UserActivityScenario.NAVIGATION
    };
    try {
      geoLocationManager.on('locationChange', req, this.onLocation);
      this.listening = true;
      hilog.info(DOMAIN, TAG, 'location subscribed');
    } catch (e) {
      const err = e as BusinessError;
      hilog.error(DOMAIN, TAG, `subscribe failed ${err.code} ${err.message}`);
      this.status = `location error ${err.code}`;
    }
  }

  private onLocation = (loc: geoLocationManager.Location): void => {
    const t: string = new Date().toTimeString().substring(0, 8);
    hilog.info(DOMAIN, TAG,
      `fix ${t} lat=${loc.latitude.toFixed(5)} lng=${loc.longitude.toFixed(5)}`);
    this.lastFix = `${t}  ${loc.latitude.toFixed(4)}, ${loc.longitude.toFixed(4)}`;
    // send the sample to your backend here
  };

  private stopLocation(): void {
    if (!this.listening) {
      return;
    }
    try {
      geoLocationManager.off('locationChange', this.onLocation);
      hilog.info(DOMAIN, TAG, 'location unsubscribed');
    } catch (e) {
      hilog.error(DOMAIN, TAG, `unsubscribe failed ${(e as BusinessError).code}`);
    }
    this.listening = false;
  }

  async stop(): Promise<void> {
    this.stopLocation();
    try {
      await backgroundTaskManager.stopBackgroundRunning(this.ctx);
      hilog.info(DOMAIN, TAG, 'task stopped');
      this.status = 'stopped';
    } catch (e) {
      hilog.error(DOMAIN, TAG, `stop failed ${(e as BusinessError).code}`);
    }
    this.running = false;
  }
}

Verification Result

References

Document

How to Use the Continuous Task in Background Tasks Kit to Obtain Location Data While the App Runs… was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

This guide explains how to access Huawei Health Service data using Postman without integrating the Health Service SDK into an application. It covers the OAuth 2.0 authorization process, obtaining an access token, and using the token to call Health Service REST APIs. This approach is useful for testing API requests, verifying data access permissions, and troubleshooting integration issues.

Implementation

Step 1. Generate the authorization URL

Replace the client_id, redirect_uri, and scope values in the following URL with your own application information.

https://oauth-login.cloud.huawei.com/oauth2/v3/authorize?response_type=code&state=state_parameter_passthrough_value&client_id=123456789&redirect_uri=https%3A%2F%2Fwww.example.com&scope=openid+https%3A%2F%2Fwww.huawei.com%2Fhealthkit%2Fheightweight.read+https%3A%2F%2Fwww.huawei.com%2Fhealthkit%2Fcalories.read&access_type=offline&display=touchCopy codeCopy code

Press enter or click to view image in full size

• Replace client_id with your application’s Client ID.
• Replace redirect_uri with your callback URL (URL-encoded).
• Update the scope parameter with the permissions corresponding to the data types you want to read.

For example:

• client_id: 123456789
• redirect_uri: https%3A%2F%2Fwww.example.com
• scope: openid https://www.huawei.com/healthkit/heightweight.read https://www.huawei.com/healthkit/calories.read

After signing in and granting the requested permissions, Huawei will redirect to your callback URL with an authorization code.

Press enter or click to view image in full size

Step 2. Exchange the authorization code for an access token

Use the authorization code returned in Step 1 to request an access token by calling the OAuth token API with the required request body.

The response will contain an access_token. Save this token, as it will be used for all subsequent Health Service REST API requests.

Press enter or click to view image in full size

For detailed authentication steps, refer to:

https://developer.huawei.com/consumer/en/doc/HMSCore-Guides/auth-example-0000001054581058

Step 3. Read Health Service data

In Postman:

• Set Authorization to Bearer Token.
• Paste the access_token obtained in Step 2.

Press enter or click to view image in full size

Then call the corresponding Health Service REST API.

Specify the startTime, endTime, and the appropriate data type depending on the data you want to read.

Important: The requests must be performed using the same Huawei account that has granted the required Health Service read permissions. Otherwise, the API may return an empty result even though the authentication is successful.

Conclusion

By following these steps, developers can authenticate with a Huawei Account, obtain an access token, and retrieve Health Service data directly through Postman. Successful data retrieval requires the appropriate read permissions, correct API parameters, and the same Huawei Account that granted the required permissions. This method provides a convenient way to validate Health Service API access and troubleshoot issues before implementing the integration in an application.

References

Document

How can I read Health Service data using Postman? was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

ArkWeb error handling becomes unusually visible on a wearable. Network failures, HTTP responses, certificate warnings, and authentication challenges all need a deterministic resolution, but a round display leaves little room for a browser-sized interface.

This article builds a wearable-compatible ArkWeb error lab in ArkTS. A 1 x 1 Web component remains mounted as the callback source, while an ArcList-based interface lets the developer trigger scenarios, resolve pending handlers, and inspect a compact event history.

The implementation was compiled with HarmonyOS 6.1.1 API 24 and exercised on an API 24 wearable emulator. It covers resource errors, HTTP status errors, SSL decisions, HTTP authentication, client-certificate requests, handler lifecycle, and verifiable results.

Problem and Requirements

The goal is not to display a full website. It is to observe and resolve ArkWeb failures correctly from a small wearable interface.

• Trigger resource-loading, HTTP, SSL, HTTP authentication, and client-certificate scenarios.
• Keep the Web component alive without allowing it to dominate the circular UI.
• Record lifecycle and error callbacks in the order they are received.
• Resolve every handler exactly once.
• Cancel pending handlers during navigation or page teardown.
• Use current HarmonyOS NEXT ArkTS APIs without third-party dependencies.

A reliable error UI must preserve callback semantics. A transport failure, an HTTP 404 response, an SSL decision, and an authentication challenge are different events and require different handling.

Background and Technical Overview

Web component and controller lifecycle

The Web component owns the ArkWeb instance and produces callbacks. WebviewController controls that instance. Construction alone does not attach the controller, so loadUrl must run only after onControllerAttached. Calling it too early can raise error 17100001.

Transport failures and HTTP responses are different

onErrorReceive reports loading failures such as DNS resolution, connection problems, and TLS failures. onHttpErrorReceive reports a valid HTTP response whose status indicates an error, such as 404 or 500. A 404 is still a server response and should not be modeled as a transport failure.

Main-frame requests and subresources

One page can request HTML, scripts, images, fonts, and other resources. Error callbacks can therefore run more than once. Use request.isMainFrame() when visible page state should react only to the top-level request, while still recording subresource failures for diagnostics.

Handler-based callbacks

SSL, HTTP authentication, and client-certificate callbacks provide decision handlers. The application must resolve each handler exactly once. The sample stores the active handler, presents a compact decision panel, and clears the reference after confirm, cancel, or ignore.

HttpAuthHandler.confirm() returning true only means that the handler accepted the invocation; it does not prove that the server accepted the credentials. Authentication success must be inferred from the callbacks that follow.

API compatibility

• Web lifecycle, resource-error, and HTTP-error events: API 8; typed event callbacks used here are API 12.
• HTTP auth, SSL, and client-auth callbacks and handlers: API 9; typed event callbacks used here are API 12.
• WebviewController.loadUrl: API 9.
• onControllerAttached: API 10.
• ArcList and ArcListItem: API 18.
• SslErrorHandler.handleCancel(abortLoading): API 20.

The exact sample calls handleCancel(true), so API 20 is its effective minimum. It was built and tested at API 24.

Implementation

1. Define deterministic error scenarios

Each scenario has a title, test URL, and retry flag. The invalid domain targets a resource error, httpbin returns HTTP 404 and HTTP Basic authentication challenges, and badssl provides controlled SSL and client-certificate endpoints.

const SCENARIOS: Array<ErrorScenario> = [
  new ErrorScenario('Resource Error',
    'add your invalid host address', true),
  new ErrorScenario('HTTP Error',
    'add your 404 address', true),
  new ErrorScenario('SSL Error',
    'add your bad SSL address', false),
  new ErrorScenario('HTTP Auth',
    'add your HTTP auth address', false),
  new ErrorScenario('Client Auth',
    'add your client certificate address', false)
];

2. Keep a minimal Web component mounted

Create one WebviewController, attach it to a 1 x 1 Web component, disable JavaScript and DOM storage, and wait for onControllerAttached before navigating. Keeping a non-zero size and leaving the component mounted preserves the callback source.

private readonly controller: webview.WebviewController =
  new webview.WebviewController();
private controllerAttached: boolean = false;
 
Web({ src: this.currentUrl, controller: this.controller })
  .width(1)
  .height(1)
  .opacity(0.01)
  .javaScriptAccess(false)
  .domStorageAccess(false)
  .onControllerAttached(() => this.controllerAttached = true)

3. Capture the page lifecycle

Track onPageBegin, onPageEnd, and onProgressChange. These callbacks describe navigation activity, not an independent success verdict. An error and onPageEnd may both appear during one navigation, which is why the UI keeps an ordered event history.

.onPageBegin((event: OnPageBeginEvent) => {
  this.loading = true;
  this.status = 'Page loading started';
  this.addEvent('PAGE_BEGIN', event.url);
})
.onPageEnd((event: OnPageEndEvent) => {
  this.loading = false;
  this.progress = 100;
  this.status = 'Page loading finished';
  this.addEvent('PAGE_END', event.url);
})
.onProgressChange((event: OnProgressChangeEvent) => {
  this.progress = event.newProgress;
})

4. Handle resource-loading failures

onErrorReceive exposes WebResourceRequest and WebResourceError. Record the code, message, and URL. Only clear the top-level loading state when request.isMainFrame() is true.

.onErrorReceive((event: OnErrorReceiveEvent) => {
  if (event.request.isMainFrame()) {
    this.loading = false;
    this.status = 'Resource error received';
  }
 
  this.addEvent(
    'RESOURCE_ERROR',
    `${event.error.getErrorCode()} · ` +
      `${event.error.getErrorInfo()} · ` +
      event.request.getRequestUrl()
  );
})

5. Handle HTTP error responses

onHttpErrorReceive exposes the response status and reason message. Record the URL and status code while preserving the distinction between main-frame and subresource requests.

.onHttpErrorReceive((event: OnHttpErrorReceiveEvent) => {
  if (event.request.isMainFrame()) {
    this.loading = false;
    this.status = 'HTTP error received';
  }
 
  this.addEvent(
    'HTTP_ERROR',
    `${event.response.getResponseCode()} ` +
      `${event.response.getReasonMessage()} · ` +
      event.request.getRequestUrl()
  );
})

6. Resolve SSL certificate errors

Store SslErrorHandler when onSslErrorEventReceive runs. Proceed calls handleConfirm(); Cancel calls handleCancel(true). Continuing past a certificate error is included only to demonstrate the callback branch.

.onSslErrorEventReceive((event: OnSslErrorEventReceiveEvent) => {
  this.loading = false;
  this.sslHandler = event.handler;
  this.addEvent('SSL_ERROR', `Certificate error ${event.error}`);
  this.showPrompt(
    PromptType.SSL,
    'SSL Warning',
    `Certificate error ${event.error}`
  );
})

Production applications should normally cancel certificate errors unless they implement a separately reviewed trust policy.

7. Resolve HTTP authentication

Return true from onHttpAuthRequest to indicate that the application will handle the request. The decision panel supplies test credentials to HttpAuthHandler.confirm() or cancels the challenge.

.onHttpAuthRequest((event: OnHttpAuthRequestEvent): boolean => {
  this.loading = false;
  this.httpAuthHandler = event.handler;
  this.addEvent('HTTP_AUTH', `${event.host} · ${event.realm}`);
  this.showPrompt(
    PromptType.HTTP_AUTH,
    'Authentication Required',
    `${event.host} · ${event.realm}`
  );
  return true;
})

8. Resolve client-certificate requests

Store ClientAuthenticationHandler and display the host, port, key types, and issuer count. This sample intentionally uses ignore() or cancel(); it does not package private keys or certificate chains.

.onClientAuthenticationRequest(
  (event: OnClientAuthenticationEvent) => {
    this.loading = false;
    this.clientAuthHandler = event.handler;
    this.addEvent(
      'CLIENT_AUTH',
      `${event.host}:${event.port} · ${event.keyTypes.join(', ')}`
    );
    this.showPrompt(
      PromptType.CLIENT_AUTH,
      'Client Certificate',
      `${event.host}:${event.port} · issuers ${event.issuers.length}`
    );
  }
)

9. Resolve every handler exactly once

Starting another scenario or leaving the page cancels any unresolved handler. After a decision, the reference is cleared so no handler can be invoked twice.

private cancelPendingHandler(): void {
  if (this.sslHandler !== undefined) {
    this.sslHandler.handleCancel(true);
    this.sslHandler = undefined;
  }
  if (this.httpAuthHandler !== undefined) {
    this.httpAuthHandler.cancel();
    this.httpAuthHandler = undefined;
  }
  if (this.clientAuthHandler !== undefined) {
    this.clientAuthHandler.cancel();
    this.clientAuthHandler = undefined;
  }
  this.clearPrompt();
}

10. Keep a bounded event history

Prepend each event to a new array and keep the latest eight entries. Replacing the array ensures ArkUI observes the state update, while the limit keeps the wearable list compact.

private addEvent(type: string, detail: string): void {
  const now: Date = new Date();
  const time: string =
    `${now.getHours().toString().padStart(2, '0')}:` +
    `${now.getMinutes().toString().padStart(2, '0')}:` +
    `${now.getSeconds().toString().padStart(2, '0')}`;
 
  const event: TraceEvent =
    new TraceEvent(this.nextEventId++, type, detail, time);
  const updated: Array<TraceEvent> = [event];
 
  for (const existing of this.events) {
    if (updated.length === 8) {
      break;
    }
    updated.push(existing);
  }
 
  this.events = updated;
}

Complete Runnable Example

The focused snippets above explain one decision at a time. The files below are the complete implementation used by the tested sample, so the application can be reproduced without inventing missing imports, state, or helper methods.

Create an ArkTS Empty Ability project with these settings:

• Device type: wearable
• Compatible SDK: HarmonyOS 6.1.1 API 24
• Target SDK: HarmonyOS 6.1.1 API 24
• Main page: pages/Index

entry/src/main/module.json5

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "wearable"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ]
      }
    ],
    "extensionAbilities": [
      {
        "name": "EntryBackupAbility",
        "srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
        "type": "backup",
        "exported": false,
        "metadata": [
          {
            "name": "ohos.extension.backup",
            "resource": "$profile:backup_config"
          }
        ],
      }
    ]
  }
}

entry/src/main/resources/base/profile/main_pages.json

{
  "src": [
    "pages/Index"
  ]
}

entry/src/main/ets/entryability/EntryAbility.ets

import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
 
const DOMAIN = 0x0000;
 
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    try {
      this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
    } catch (err) {
      hilog.error(DOMAIN, 'testTag', 'Failed to set colorMode. Cause: %{public}s', JSON.stringify(err));
    }
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
  }
 
  onDestroy(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
  }
 
  onWindowStageCreate(windowStage: window.WindowStage): void {
    // Main window is created, set main page for this ability
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
 
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
        return;
      }
      hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
    });
  }
 
  onWindowStageDestroy(): void {
    // Main window is destroyed, release UI related resources
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
  }
 
  onForeground(): void {
    // Ability has brought to foreground
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
  }
 
  onBackground(): void {
    // Ability has back to background
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
  }
}

entry/src/main/ets/pages/Index.ets

import { webview } from '@kit.ArkWeb';
import { ArcList, ArcListAttribute, ArcListItem, ArcListItemAttribute } from '@kit.ArkUI';
 
enum PromptType {
  NONE = 'NONE',
  SSL = 'SSL',
  HTTP_AUTH = 'HTTP_AUTH',
  CLIENT_AUTH = 'CLIENT_AUTH'
}
 
class ErrorScenario {
  readonly title: string;
  readonly url: string;
  readonly retryable: boolean;
 
  constructor(
    title: string,
    url: string,
    retryable: boolean
  ) {
    this.title = title;
    this.url = url;
    this.retryable = retryable;
  }
}
 
class TraceEvent {
  readonly id: number;
  readonly type: string;
  readonly detail: string;
  readonly time: string;
 
  constructor(
    id: number,
    type: string,
    detail: string,
    time: string
  ) {
    this.id = id;
    this.type = type;
    this.detail = detail;
    this.time = time;
  }
}
 
const SCENARIOS: Array<ErrorScenario> = [
  new ErrorScenario('Resource Error', 'add your invalid host address', true),
  new ErrorScenario('HTTP Error', 'add your 404 address', true),
  new ErrorScenario('SSL Error', 'add your bad SSL address', false),
  new ErrorScenario('HTTP Auth', 'add your HTTP auth address', false),
  new ErrorScenario('Client Auth', 'add your client certificate address', false)
];
 
@Entry
@Component
struct Index {
  @State private currentUrl: string = 'about:blank';
  @State private status: string = 'Choose a scenario';
  @State private progress: number = 0;
  @State private loading: boolean = false;
  @State private events: Array<TraceEvent> = [];
  @State private promptType: PromptType = PromptType.NONE;
  @State private promptTitle: string = '';
  @State private promptMessage: string = '';
  @State private username: string = 'demo';
  @State private password: string = 'password';
 
  private readonly controller: webview.WebviewController = new webview.WebviewController();
  private controllerAttached: boolean = false;
  private nextEventId: number = 1;
  private lastScenario: ErrorScenario | undefined = undefined;
  private sslHandler: SslErrorHandler | undefined = undefined;
  private httpAuthHandler: HttpAuthHandler | undefined = undefined;
  private clientAuthHandler: ClientAuthenticationHandler | undefined = undefined;
 
  aboutToDisappear(): void {
    this.cancelPendingHandler();
  }
 
  private runScenario(scenario: ErrorScenario): void {
    this.cancelPendingHandler();
    this.lastScenario = scenario;
    this.currentUrl = scenario.url;
    this.status = `Loading ${scenario.title}`;
    this.loading = true;
    this.progress = 0;
    if (this.controllerAttached) {
      try {
        this.controller.loadUrl(scenario.url);
      } catch (error) {
        this.loading = false;
        this.addEvent('LOAD_ERROR', JSON.stringify(error));
      }
    }
  }
 
  private retry(): void {
    if (this.lastScenario === undefined || !this.lastScenario.retryable) {
      this.status = 'Retry is not available';
      return;
    }
    this.runScenario(this.lastScenario);
  }
 
  private addEvent(type: string, detail: string): void {
    const now: Date = new Date();
    const time: string = `${now.getHours().toString().padStart(2, '0')}:` +
      `${now.getMinutes().toString().padStart(2, '0')}:` +
      `${now.getSeconds().toString().padStart(2, '0')}`;
    const event: TraceEvent = new TraceEvent(this.nextEventId++, type, detail, time);
    const updated: Array<TraceEvent> = [event];
    for (const existing of this.events) {
      if (updated.length === 8) {
        break;
      }
      updated.push(existing);
    }
    this.events = updated;
  }
 
  private showPrompt(type: PromptType, title: string, message: string): void {
    this.promptType = type;
    this.promptTitle = title;
    this.promptMessage = message;
    this.status = title;
  }
 
  private confirmPrompt(): void {
    if (this.promptType === PromptType.SSL && this.sslHandler !== undefined) {
      this.sslHandler.handleConfirm();
      this.sslHandler = undefined;
      this.status = 'SSL request continued';
    } else if (this.promptType === PromptType.HTTP_AUTH && this.httpAuthHandler !== undefined) {
      const accepted: boolean = this.httpAuthHandler.confirm(this.username, this.password);
      this.httpAuthHandler = undefined;
      this.status = accepted ? 'Credentials accepted' : 'Credentials rejected';
    }
    this.clearPrompt();
  }
 
  private cancelPrompt(): void {
    this.cancelPendingHandler();
    this.status = 'Request cancelled';
  }
 
  private ignoreClientAuth(): void {
    if (this.clientAuthHandler !== undefined) {
      this.clientAuthHandler.ignore();
      this.clientAuthHandler = undefined;
      this.status = 'Client certificate request ignored';
    }
    this.clearPrompt();
  }
 
  private cancelPendingHandler(): void {
    if (this.sslHandler !== undefined) {
      this.sslHandler.handleCancel(true);
      this.sslHandler = undefined;
    }
    if (this.httpAuthHandler !== undefined) {
      this.httpAuthHandler.cancel();
      this.httpAuthHandler = undefined;
    }
    if (this.clientAuthHandler !== undefined) {
      this.clientAuthHandler.cancel();
      this.clientAuthHandler = undefined;
    }
    this.clearPrompt();
  }
 
  private clearPrompt(): void {
    this.promptType = PromptType.NONE;
    this.promptTitle = '';
    this.promptMessage = '';
  }
 
  @Builder
  private promptPanel() {
    Stack({ alignContent: Alignment.Center }) {
      Column({ space: 7 }) {
        Text(this.promptTitle)
          .fontSize(15)
          .fontWeight(FontWeight.Bold)
          .fontColor('#F8FAFC')
          .margin({ top: 20 })
        Text(this.promptMessage)
          .fontSize(9)
          .fontColor('#A9B8CC')
          .maxLines(2)
          .width('74%')
          .textAlign(TextAlign.Center)
        if (this.promptType === PromptType.HTTP_AUTH) {
          TextInput({ text: this.username, placeholder: 'Username' })
            .width('70%')
            .height(34)
            .fontSize(11)
            .onChange((value: string) => this.username = value)
          TextInput({ text: this.password, placeholder: 'Password' })
            .width('70%')
            .height(34)
            .fontSize(11)
            .type(InputType.Password)
            .onChange((value: string) => this.password = value)
        }
        Row({ space: 6 }) {
          if (this.promptType !== PromptType.CLIENT_AUTH) {
            Button(this.promptType === PromptType.SSL ? 'Proceed' : 'Confirm')
              .height(34)
              .fontSize(10)
              .onClick(() => this.confirmPrompt())
          } else {
            Button('Ignore')
              .height(34)
              .fontSize(10)
              .onClick(() => this.ignoreClientAuth())
          }
          Button('Cancel')
            .height(34)
            .fontSize(10)
            .onClick(() => this.cancelPrompt())
        }
      }
      .width('86%')
      .padding({ left: 12, right: 12, bottom: 18 })
      .borderRadius(28)
      .backgroundColor('#172A46')
      .alignItems(HorizontalAlign.Center)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#D907111F')
  }
 
  build() {
    Stack({ alignContent: Alignment.Center }) {
      ArcList() {
        ArcListItem() {
          Column({ space: 3 }) {
            Text('WEB ERROR LAB')
              .fontSize(15)
              .fontWeight(FontWeight.Bold)
              .fontColor('#EAF2FF')
            Text(this.status)
              .fontSize(9)
              .fontColor('#79C8FF')
              .maxLines(1)
            if (this.loading) {
              Progress({ value: this.progress, total: 100, type: ProgressType.Linear })
                .width('64%')
                .height(3)
                .color('#38BDF8')
            }
          }
          .width('100%')
          .alignItems(HorizontalAlign.Center)
          .margin({ top: 20, bottom: 4 })
        }
        .height(62)
 
        ForEach(SCENARIOS, (scenario: ErrorScenario) => {
          ArcListItem() {
            Button(scenario.title)
              .width('88%')
              .height(38)
              .fontSize(12)
              .fontColor('#EAF2FF')
              .backgroundColor('#17345A')
              .onClick(() => this.runScenario(scenario))
          }
          .height(42)
          .autoScale(true)
        }, (scenario: ErrorScenario) => scenario.title)
 
        ForEach(this.events, (event: TraceEvent) => {
          ArcListItem() {
            Column({ space: 1 }) {
              Row() {
                Text(event.type)
                  .fontSize(9)
                  .fontWeight(FontWeight.Bold)
                  .fontColor('#7DD3FC')
                  .layoutWeight(1)
                Text(event.time).fontSize(8).fontColor('#718096')
              }
              .width('100%')
              Text(event.detail)
                .fontSize(8)
                .fontColor('#CBD5E1')
                .maxLines(2)
                .width('100%')
            }
            .width('88%')
            .padding({ left: 10, right: 10, top: 6, bottom: 6 })
            .borderRadius(14)
            .backgroundColor('#102033')
          }
          .height(55)
          .autoScale(true)
        }, (event: TraceEvent) => event.id.toString())
 
        ArcListItem() {
          Row({ space: 6 }) {
            Button('Retry').height(34).fontSize(10).onClick(() => this.retry())
            Button('Clear').height(34).fontSize(10).onClick(() => this.events = [])
          }
          .width('100%')
          .justifyContent(FlexAlign.Center)
          .margin({ bottom: 30 })
        }
        .height(68)
      }
      .width('100%')
      .height('100%')
      .scrollBar(BarState.Off)
      .backgroundColor('#07111F')
 
      Web({ src: this.currentUrl, controller: this.controller })
        .width(1)
        .height(1)
        .opacity(0.01)
        .javaScriptAccess(false)
        .domStorageAccess(false)
        .onControllerAttached(() => this.controllerAttached = true)
        .onPageBegin((event: OnPageBeginEvent) => {
          this.loading = true;
          this.status = 'Page loading started';
          this.addEvent('PAGE_BEGIN', event.url);
        })
        .onPageEnd((event: OnPageEndEvent) => {
          this.loading = false;
          this.progress = 100;
          this.status = 'Page loading finished';
          this.addEvent('PAGE_END', event.url);
        })
        .onProgressChange((event: OnProgressChangeEvent) => this.progress = event.newProgress)
        .onErrorReceive((event: OnErrorReceiveEvent) => {
          if (event.request.isMainFrame()) {
            this.loading = false;
            this.status = 'Resource error received';
          }
          this.addEvent(
            'RESOURCE_ERROR',
            `${event.error.getErrorCode()} · ${event.error.getErrorInfo()} · ${event.request.getRequestUrl()}`
          );
        })
        .onHttpErrorReceive((event: OnHttpErrorReceiveEvent) => {
          if (event.request.isMainFrame()) {
            this.loading = false;
            this.status = 'HTTP error received';
          }
          this.addEvent(
            'HTTP_ERROR',
            `${event.response.getResponseCode()} ${event.response.getReasonMessage()} · ` +
              event.request.getRequestUrl()
          );
        })
        .onSslErrorEventReceive((event: OnSslErrorEventReceiveEvent) => {
          this.loading = false;
          this.sslHandler = event.handler;
          this.addEvent('SSL_ERROR', `Certificate error ${event.error}`);
          this.showPrompt(PromptType.SSL, 'SSL Warning', `Certificate error ${event.error}`);
        })
        .onHttpAuthRequest((event: OnHttpAuthRequestEvent): boolean => {
          this.loading = false;
          this.httpAuthHandler = event.handler;
          this.addEvent('HTTP_AUTH', `${event.host} · ${event.realm}`);
          this.showPrompt(PromptType.HTTP_AUTH, 'Authentication Required', `${event.host} · ${event.realm}`);
          return true;
        })
        .onClientAuthenticationRequest((event: OnClientAuthenticationEvent) => {
          this.loading = false;
          this.clientAuthHandler = event.handler;
          this.addEvent('CLIENT_AUTH', `${event.host}:${event.port} · ${event.keyTypes.join(', ')}`);
          this.showPrompt(
            PromptType.CLIENT_AUTH,
            'Client Certificate',
            `${event.host}:${event.port} · issuers ${event.issuers.length}`
          );
        })
 
      if (this.promptType !== PromptType.NONE) {
        this.promptPanel();
      }
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#07111F')
  }
}

Run the Sample

Build the project from its root directory:

hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

A signing profile is required only for installation on physical hardware. Configure it in DevEco Studio instead of copying another developer’s machine-specific signing values.

On the wearable emulator, run each scenario and verify the visible callback history and each handler decision panel.

Testing and Results

The implementation was validated as an application, not only as isolated code. It was clean-built with HarmonyOS 6.1.1 API 24, installed on a wearable emulator, and operated through the real interface.

• Build: BUILD SUCCESSFUL with no ArkTS compiler warning.
• Environment: HarmonyOS 6.1.0.125 API 24 wearable emulator, 466 x 466 display.
• Application start: EntryAbility reached the foreground and ArkWeb started without a crash.
• Resource Error: During the recorded emulator run, onErrorReceive reported RESOURCE_ERROR, code -106, and ERR_INTERNET_DISCONNECTED for the intentionally invalid host. The exact transport code can vary with emulator connectivity; with an active network, an unresolvable host may instead produce a DNS-related error. The reliable assertion is that onErrorReceive fires for the main-frame request, not that every environment returns the same code.
• HTTP Error: onHttpErrorReceive recorded main-frame status 404; page begin and page end were also observed.
• SSL Error: onSslErrorEventReceive recorded certificate error 3. Proceed reached PAGE_END; Cancel also completed without a crash.
• HTTP Auth: onHttpAuthRequest reported httpbin.org and realm Fake Realm. The demo credentials resolved the challenge and reached PAGE_END.
• Client Auth: onClientAuthenticationRequest reported client.badssl.com:443, RSA/ECDSA key types, and one issuer. Ignore resolved the handler.

The result is driven by real ArkWeb callbacks. It does not simulate errors or progress with a timer.

Explanation: Why This Design Works

• A persistent, non-zero Web component preserves the callback source.
• Controller attachment prevents loadUrl from running before ArkWeb is ready.
• Main-frame checks prevent subresource failures from replacing the primary page status.
• Dedicated handler references make pending decisions explicit and cancellable.
• A bounded immutable event update is predictable for ArkUI state observation and wearable memory use.
• JavaScript and DOM storage stay disabled because this diagnostic sample does not require them.

Limitations and Production Considerations

Public test services

httpbin.org and badssl.com are test dependencies, not production services. Availability, redirects, realm text, certificates, and subresource behavior can change.

SSL security

Proceeding through an SSL error weakens certificate protection for that request. The Proceed branch exists only for controlled testing. A production application should cancel unless it has a reviewed trust policy.

Client-certificate credentials

The sample does not call ClientAuthenticationHandler.confirm() because it does not ship a private key or certificate chain. Packaging such credentials inside an application bundle would be insecure.

Resource cost

The hidden 1 x 1 Web component still creates an ArkWeb instance and consumes memory, CPU, and network resources. It is not a substitute for a normal HTTP client.

State and recovery

The event history is held in memory, limited to eight entries, and not persisted across process recreation. The sample does not implement retry backoff, offline detection, custom error pages, certificate pinning, or certificate-chain inspection.

Device validation

Emulator verification does not replace testing on target hardware with its real certificate store, network policy, proxy configuration, authentication behavior, and performance characteristics.

Conclusion

Reliable ArkWeb error handling on a wearable depends less on visual browser space and more on correct callback semantics. Keeping a minimal Web component mounted, waiting for controller attachment, separating transport and HTTP failures, and resolving each handler exactly once produces a compact implementation that is both observable and safe to extend.

The resulting sample gives developers a practical baseline for ArkWeb diagnostics on HarmonyOS NEXT wearables. Production applications should retain this lifecycle discipline while replacing public endpoints, test credentials, and permissive SSL behavior with reviewed production policies.

Key takeaway: Keep the Web component mounted, wait for controller attachment, distinguish transport and HTTP failures, resolve every handler exactly once, and let verified callbacks drive the wearable UI.

Related Resources and References

• Huawei Developers — Web component events
• Huawei Developers — WebviewController
• Huawei Developers — SslErrorHandler
• Huawei Developers — HttpAuthHandler
• Huawei Developers — ClientAuthenticationHandler
• Huawei Developers — ArcList
• Huawei Developers — ArcListItem
• Huawei Developers — Wearable app development

ArkWeb Error Handling in HarmonyOS NEXT Wearable Apps with ArkTS was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Downloading a file is easy until the interface must stay honest. A wearable user expects the progress ring, available actions, error state, and history to reflect the real transfer not a timer that merely looks convincing.

Introduction

ArkWeb provides the download lifecycle through WebviewController, WebDownloadDelegate, and WebDownloadItem. The engineering challenge is not starting the transfer. It is translating asynchronous callbacks into a small, predictable state machine that ArkUI can render safely.

This article demonstrates that design on HarmonyOS NEXT with ArkTS. It focuses on controller attachment, destination selection, progress propagation, action guards, cancellation semantics, and verifiable results.

Problem and Requirements

The download surface must:

• Start a network download through the active ArkWeb controller.
• Accept the transfer into the application sandbox in onBeforeDownload.
• Render real progress on a round, space-constrained display.
• Guard pause, continue, cancel, restart, and download-again actions by current state.
• Distinguish a user cancellation from a genuine failure.
• Record completed, canceled, and failed transfers for the current session.

Background and Technical Overview

WebviewController.startDownload(url) initiates a request. WebDownloadDelegate.onBeforeDownload then supplies the related WebDownloadItem. The application sets a destination and calls item.start(destination). Later callbacks deliver progress, completion, or interruption.

A WebviewController is not ready merely because it was constructed. It must be attached to a mounted Web component, and controller-dependent work must wait for onControllerAttached. A visually hidden Web component is therefore part of the architecture, not a decorative detail.

API compatibility

• Web component: API 8.
• onControllerAttached: API 10.
• setDownloadDelegate, startDownload, callbacks, and transfer controls: API 11.
• UIAbilityContext.filesDir: API 9.

The runtime device must expose SystemCapability.Web.Webview.Core. Declaring a wearable device type does not add ArkWeb support to unsupported hardware.

State before UI

The UI should not decide what a download means. The service owns one snapshot containing engine state, transfer state, progress, URL, file name, destination, and error message. Pages subscribe to that snapshot and derive labels and controls from it.

export enum DownloadStatus {
  Idle = 'Idle',
  Downloading = 'Downloading',
  Paused = 'Paused',
  Canceled = 'Canceled',
  Completed = 'Completed',
  Failed = 'Failed'
}

Implementation

1. Keep the Web engine alive

The engine host owns one WebviewController. After attachment, it passes the controller and sandbox directory to the service. The Web component stays mounted in the root stack so navigation cannot destroy the engine.

@Component
export struct DownloadEngineHost {
  private readonly webController: webview.WebviewController =
    new webview.WebviewController();

  build() {
    Web({
      src: 'about:blank',
      controller: this.webController
    })
      .height(1)
      .opacity(0.01)
      .onControllerAttached((): void => {
        const context = this.getUIContext().getHostContext()
          as common.UIAbilityContext;

        appWebDownloadService.initialize(
          this.webController,
          context.filesDir
        );
      });
  }
}

2. Attach one delegate to the active controller

The service configures callbacks once and attaches the delegate. can throw setDownloadDelegate initialization error 17100001 when its controller is not associated with a Web component, so setup belongs after attachment and inside try/catch

initialize(
  controller: webview.WebviewController,
  filesDir: string
): void {
  this.controller = controller;
  this.filesDir = filesDir;
  this.configureDelegate();

try {
    this.controller.setDownloadDelegate(this.downloadDelegate);
    this.snapshot.engineState = EngineState.Attached;
    this.notifySnapshot();
  } catch (error) {
    this.publish(DownloadStatus.Failed, 0,
      'Unable to attach the delegate.');
  }
}

3. Initiate the request and prepare the destination

A repeatable Download Again action must not collide with an existing file. Before initiating the request, the service creates a path inside filesDir, removes an existing same-name file, resets transfer flags, and publishes Idle. Because the destination is app-private, broad storage access is unnecessary.

startDownload(sourceUrl: string, fileName: string): void {
  this.sourceUrl = sourceUrl;
  this.fileName = fileName;
  this.filePath = this.filesDir + '/' + this.fileName;
  this.cancelRequested = false;
  this.activityRecorded = false;

try {
    if (fileIo.accessSync(this.filePath)) {
      fileIo.unlinkSync(this.filePath);
    }
    this.publish(DownloadStatus.Idle, 0, '');
    this.controller?.startDownload(this.sourceUrl);
  } catch (error) {
    this.publish(DownloadStatus.Failed, 0,
      'Unable to start the download.');
  }
}

4. Accept the item and publish real progress

The request becomes controllable when ArkWeb invokes onBeforeDownload. The service stores the item, accepts it at the prepared path, and publishes Downloading. Updates are real percentages from the item. Because the API can report a value outside the UI range, the example clamps it before sending it to the ring.

this.downloadDelegate.onBeforeDownload(
  (item: webview.WebDownloadItem): void => {
    this.activeItem = item;

    try {
      item.start(this.filePath);
      this.publish(DownloadStatus.Downloading, 0, '');
    } catch (error) {
      this.publish(
        DownloadStatus.Failed,
        0,
        'Unable to create the file.'
      );
    }
  }
);

this.downloadDelegate.onDownloadUpdated(
  (item: webview.WebDownloadItem): void => {
    this.activeItem = item;

    if (
      this.snapshot.status === DownloadStatus.Paused ||
      this.snapshot.status === DownloadStatus.Canceled
    ) {
      return;
    }

    this.publish(
      DownloadStatus.Downloading,
      Math.max(
        0,
        Math.min(100, item.getPercentComplete())
      ),
      ''
    );
  }
);

A late update callback must not overwrite a user-visible Paused or Canceled state with Downloading. The service, rather than the page, enforces that rule.

5. Map state to pause, continue, and cancel

WebDownloadItem methods are state-sensitive. Pause requires a started task, while resume requires a paused task. Guarding each operation before calling ArkWeb prevents avoidable errors and keeps the visible state aligned with the item.

Controlling the Active Transfer

pauseDownload(): void {
  if (
    this.activeItem === undefined ||
    this.snapshot.status !== DownloadStatus.Downloading
  ) {
    return;
  }

  this.activeItem.pause();
  this.publish(
    DownloadStatus.Paused,
    this.snapshot.progress,
    ''
  );
}

resumeDownload(): void {
  if (
    this.activeItem === undefined ||
    this.snapshot.status !== DownloadStatus.Paused
  ) {
    return;
  }

  this.activeItem.resume();
  this.publish(
    DownloadStatus.Downloading,
    this.snapshot.progress,
    ''
  );
}

cancelDownload(): void {
  if (this.activeItem === undefined) {
    return;
  }

  this.cancelRequested = true;
  this.activeItem.cancel();

  this.publish(
    DownloadStatus.Canceled,
    this.snapshot.progress,
    ''
  );

  this.recordActivity(DownloadStatus.Canceled);
}

Cancellation is not a generic failure

ArkWeb reports interrupted and canceled transfers through onDownloadFailed. Without an explicit cancellation flag, the interface would briefly show Canceled and then be overwritten by Failed. The service records user intent and preserves the last known progress when a canceled item reports zero.

const progress: number = this.clampProgress(
  item.getPercentComplete()
);

if (this.cancelRequested) {
  this.publish(
    DownloadStatus.Canceled,
    Math.max(this.snapshot.progress, progress),
    ''
  );

  this.recordActivity(DownloadStatus.Canceled);
  return;
}

const message: string =
  'Download failed (error ' +
  item.getLastErrorCode() +
  ').';

this.publish(
  DownloadStatus.Failed,
  progress,
  message
);

Completion, Activity, and ArkUI Binding

Completion is intentionally simple: publish 100 percent, clear the error, and record one terminal event. An activityRecorded guard prevents duplicate history rows.

this.downloadDelegate.onDownloadFinish(
  (item: webview.WebDownloadItem): void => {
    this.activeItem = item;
    this.publish(DownloadStatus.Completed, 100, '');
    this.recordActivity(DownloadStatus.Completed);
  }
);

The page subscribes when it appears, copies snapshot fields into ArkUI state, and unsubscribes when it disappears. Button labels are pure functions of DownloadStatus: Downloading maps to Pause, Paused to Continue, Failed or Canceled to Restart, and Completed to Again.

Complete Runnable Example

The focused snippets above explain the download lifecycle one decision at a time. This section contains the complete files used by the tested sample, so the application can be reproduced without filling in missing classes, imports, state, or helper methods.

Create an ArkTS Empty Ability project with the following settings:

• Device type: wearable
• Main page: pages/Index

Keep the generated EntryAbility.ets and main_pages.json files unchanged.

Required manifest change

ArkWeb needs network access. Add the following property inside the generated module object in entry/src/main/module.json5:

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  }
]

The project must also target a wearable. If the project was created with the wearable template, the generated module already contains this value:

"deviceTypes": [
  "wearable"
]

Project structure

Add or replace these four files:

entry/src/main/ets/
├── components/
│   └── DownloadEngineHost.ets
├── model/
│   └── DownloadModels.ets
├── pages/
│   └── Index.ets
└── service/
    └── AppWebDownloadService.ets

entry/src/main/ets/model/DownloadModels.ets

export enum DownloadStatus {
  Idle = 'Idle',
  Downloading = 'Downloading',
  Paused = 'Paused',
  Canceled = 'Canceled',
  Completed = 'Completed',
  Failed = 'Failed'
}
export enum EngineState {
  Waiting = 'Waiting',
  Attached = 'Attached'
}
export class DownloadSnapshot {
  engineState: EngineState = EngineState.Waiting;
  status: DownloadStatus = DownloadStatus.Idle;
  progress: number = 0;
  fileName: string = '';
  filePath: string = '';
  sourceUrl: string = '';
  errorMessage: string = '';
  copy(): DownloadSnapshot {
    const snapshot: DownloadSnapshot = new DownloadSnapshot();
    snapshot.engineState = this.engineState;
    snapshot.status = this.status;
    snapshot.progress = this.progress;
    snapshot.fileName = this.fileName;
    snapshot.filePath = this.filePath;
    snapshot.sourceUrl = this.sourceUrl;
    snapshot.errorMessage = this.errorMessage;
    return snapshot;
  }
}
export class DownloadActivityRecord {
  id: string = '';
  title: string = '';
  status: DownloadStatus = DownloadStatus.Idle;
  progress: number = 0;
  errorMessage: string = '';
  createdAt: number = 0;
}
export type DownloadListener = (snapshot: DownloadSnapshot) => void;
export type ActivityListener = (records: Array<DownloadActivityRecord>) => void;

entry/src/main/ets/service/AppWebDownloadService.ets

import { webview } from '@kit.ArkWeb';
import { fileIo } from '@kit.CoreFileKit';
import {
  ActivityListener,
  DownloadActivityRecord,
  DownloadListener,
  DownloadSnapshot,
  DownloadStatus,
  EngineState
} from '../model/DownloadModels';
export class AppWebDownloadService {
  private controller: webview.WebviewController | undefined = undefined;
  private activeItem: webview.WebDownloadItem | undefined = undefined;
  private filesDir: string = '';
  private sourceUrl: string = '';
  private fileName: string = '';
  private filePath: string = '';
  private snapshot: DownloadSnapshot = new DownloadSnapshot();
  private activityRecords: Array<DownloadActivityRecord> = [];
  private listeners: Array<DownloadListener> = [];
  private activityListeners: Array<ActivityListener> = [];
  private delegateConfigured: boolean = false;
  private cancelRequested: boolean = false;
  private activityRecorded: boolean = false;
  private readonly downloadDelegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
  initialize(controller: webview.WebviewController, filesDir: string): void {
    this.controller = controller;
    this.filesDir = filesDir;
    this.configureDelegate();
    try {
      this.controller.setDownloadDelegate(this.downloadDelegate);
      this.snapshot.engineState = EngineState.Attached;
      this.notifySnapshot();
    } catch (error) {
      this.publish(DownloadStatus.Failed, 0, `Unable to attach the delegate: ${JSON.stringify(error)}`);
    }
  }
  subscribe(listener: DownloadListener): () => void {
    this.listeners.push(listener);
    listener(this.snapshot.copy());
    return (): void => {
      const index: number = this.listeners.indexOf(listener);
      if (index >= 0) {
        this.listeners.splice(index, 1);
      }
    };
  }
  subscribeActivity(listener: ActivityListener): () => void {
    this.activityListeners.push(listener);
    listener(this.activityRecords.slice());
    return (): void => {
      const index: number = this.activityListeners.indexOf(listener);
      if (index >= 0) {
        this.activityListeners.splice(index, 1);
      }
    };
  }
  startDownload(sourceUrl: string, fileName: string): void {
    if (this.controller === undefined || this.filesDir.length === 0) {
      this.publish(DownloadStatus.Failed, 0, 'The Web engine is not ready.');
      return;
    }
    this.sourceUrl = sourceUrl;
    this.fileName = fileName;
    this.filePath = `${this.filesDir}/${this.fileName}`;
    this.activeItem = undefined;
    this.cancelRequested = false;
    this.activityRecorded = false;
    try {
      if (fileIo.accessSync(this.filePath)) {
        fileIo.unlinkSync(this.filePath);
      }
      this.publish(DownloadStatus.Idle, 0, '');
      this.controller.startDownload(this.sourceUrl);
    } catch (error) {
      this.publish(DownloadStatus.Failed, 0, `Unable to start: ${JSON.stringify(error)}`);
      this.recordActivity(DownloadStatus.Failed, this.snapshot.errorMessage);
    }
  }
  pauseDownload(): void {
    if (this.activeItem === undefined || this.snapshot.status !== DownloadStatus.Downloading) {
      return;
    }
    try {
      this.activeItem.pause();
      this.publish(DownloadStatus.Paused, this.snapshot.progress, '');
    } catch (error) {
      this.publish(DownloadStatus.Failed, this.snapshot.progress, `Unable to pause: ${JSON.stringify(error)}`);
      this.recordActivity(DownloadStatus.Failed, this.snapshot.errorMessage);
    }
  }
  resumeDownload(): void {
    if (this.activeItem === undefined || this.snapshot.status !== DownloadStatus.Paused) {
      return;
    }
    try {
      this.activeItem.resume();
      this.publish(DownloadStatus.Downloading, this.snapshot.progress, '');
    } catch (error) {
      this.publish(DownloadStatus.Failed, this.snapshot.progress, `Unable to continue: ${JSON.stringify(error)}`);
      this.recordActivity(DownloadStatus.Failed, this.snapshot.errorMessage);
    }
  }
  cancelDownload(): void {
    if (this.activeItem === undefined ||
      (this.snapshot.status !== DownloadStatus.Downloading && this.snapshot.status !== DownloadStatus.Paused)) {
      return;
    }
    this.cancelRequested = true;
    try {
      this.activeItem.cancel();
      this.publish(DownloadStatus.Canceled, this.snapshot.progress, '');
      this.recordActivity(DownloadStatus.Canceled);
    } catch (error) {
      this.cancelRequested = false;
      this.publish(DownloadStatus.Failed, this.snapshot.progress, `Unable to cancel: ${JSON.stringify(error)}`);
      this.recordActivity(DownloadStatus.Failed, this.snapshot.errorMessage);
    }
  }
  restartDownload(): void {
    if (this.sourceUrl.length === 0 || this.fileName.length === 0) {
      return;
    }
    this.startDownload(this.sourceUrl, this.fileName);
  }
  clearActivity(): void {
    this.activityRecords = [];
    this.notifyActivity();
  }
  private configureDelegate(): void {
    if (this.delegateConfigured) {
      return;
    }
    this.delegateConfigured = true;
    this.downloadDelegate.onBeforeDownload((item: webview.WebDownloadItem): void => {
      this.activeItem = item;
      try {
        item.start(this.filePath);
        this.publish(DownloadStatus.Downloading, 0, '');
      } catch (error) {
        this.publish(DownloadStatus.Failed, 0, `Unable to create the file: ${JSON.stringify(error)}`);
        this.recordActivity(DownloadStatus.Failed, this.snapshot.errorMessage);
      }
    });
    this.downloadDelegate.onDownloadUpdated((item: webview.WebDownloadItem): void => {
      this.activeItem = item;
      if (this.snapshot.status === DownloadStatus.Paused || this.snapshot.status === DownloadStatus.Canceled) {
        return;
      }
      this.publish(DownloadStatus.Downloading, this.clampProgress(item.getPercentComplete()), '');
    });
    this.downloadDelegate.onDownloadFinish((item: webview.WebDownloadItem): void => {
      this.activeItem = item;
      this.publish(DownloadStatus.Completed, 100, '');
      this.recordActivity(DownloadStatus.Completed);
    });
    this.downloadDelegate.onDownloadFailed((item: webview.WebDownloadItem): void => {
      this.activeItem = item;
      const progress: number = this.clampProgress(item.getPercentComplete());
      if (this.cancelRequested) {
        this.publish(DownloadStatus.Canceled, Math.max(this.snapshot.progress, progress), '');
        this.recordActivity(DownloadStatus.Canceled);
        return;
      }
      const message: string = `Download failed (error ${item.getLastErrorCode()}).`;
      this.publish(DownloadStatus.Failed, progress, message);
      this.recordActivity(DownloadStatus.Failed, message);
    });
  }
  private clampProgress(value: number): number {
    return Math.max(0, Math.min(100, value));
  }
  private publish(status: DownloadStatus, progress: number, errorMessage: string): void {
    this.snapshot.status = status;
    this.snapshot.progress = progress;
    this.snapshot.sourceUrl = this.sourceUrl;
    this.snapshot.fileName = this.fileName;
    this.snapshot.filePath = this.filePath;
    this.snapshot.errorMessage = errorMessage;
    this.notifySnapshot();
  }
  private notifySnapshot(): void {
    const snapshot: DownloadSnapshot = this.snapshot.copy();
    for (const listener of this.listeners) {
      listener(snapshot);
    }
  }
  private recordActivity(status: DownloadStatus, errorMessage: string = ''): void {
    if (this.activityRecorded) {
      return;
    }
    this.activityRecorded = true;
    const record: DownloadActivityRecord = new DownloadActivityRecord();
    record.id = `${Date.now()}`;
    record.title = this.fileName;
    record.status = status;
    record.progress = this.snapshot.progress;
    record.errorMessage = errorMessage;
    record.createdAt = Date.now();
    this.activityRecords = [record, ...this.activityRecords];
    this.notifyActivity();
  }
  private notifyActivity(): void {
    const records: Array<DownloadActivityRecord> = this.activityRecords.slice();
    for (const listener of this.activityListeners) {
      listener(records);
    }
  }
}
export const appWebDownloadService: AppWebDownloadService = new AppWebDownloadService();

entry/src/main/ets/components/DownloadEngineHost.ets

import { common } from '@kit.AbilityKit';
import { webview } from '@kit.ArkWeb';
import { appWebDownloadService } from '../service/AppWebDownloadService';
@Component
export struct DownloadEngineHost {
  private readonly webController: webview.WebviewController = new webview.WebviewController();
  build() {
    Web({ src: 'about:blank', controller: this.webController })
      .width(1)
      .height(1)
      .opacity(0.01)
      .onControllerAttached((): void => {
        const context: common.UIAbilityContext =
          this.getUIContext().getHostContext() as common.UIAbilityContext;
        appWebDownloadService.initialize(this.webController, context.filesDir);
      });
  }
}

entry/src/main/ets/pages/Index.ets

import { ArcList, ArcListItem } from '@kit.ArkUI';
import { DownloadEngineHost } from '../components/DownloadEngineHost';
import { DownloadActivityRecord, DownloadSnapshot, DownloadStatus, EngineState } from '../model/DownloadModels';
import { appWebDownloadService } from '../service/AppWebDownloadService';
enum AppPage {
  Download = 'Download',
  Activity = 'Activity',
  System = 'System'
}
const DOWNLOAD_URL: string = 'add your download address';
const DOWNLOAD_FILE_NAME: string = 'add your download name';
@Entry
@Component
struct Index {
  @State private page: AppPage = AppPage.Download;
  @State private engineState: EngineState = EngineState.Waiting;
  @State private status: DownloadStatus = DownloadStatus.Idle;
  @State private progressValue: number = 0;
  @State private fileName: string = '';
  @State private errorMessage: string = '';
  @State private records: Array<DownloadActivityRecord> = [];
  private unsubscribe: (() => void) | undefined = undefined;
  private unsubscribeActivity: (() => void) | undefined = undefined;
  aboutToAppear(): void {
    this.unsubscribe = appWebDownloadService.subscribe((snapshot: DownloadSnapshot): void => {
      this.engineState = snapshot.engineState;
      this.status = snapshot.status;
      this.progressValue = snapshot.progress;
      this.fileName = snapshot.fileName;
      this.errorMessage = snapshot.errorMessage;
    });
    this.unsubscribeActivity = appWebDownloadService.subscribeActivity(
      (records: Array<DownloadActivityRecord>): void => {
        this.records = records;
      }
    );
  }
  aboutToDisappear(): void {
    if (this.unsubscribe !== undefined) {
      this.unsubscribe();
    }
    if (this.unsubscribeActivity !== undefined) {
      this.unsubscribeActivity();
    }
  }
  private startDownload(): void {
    appWebDownloadService.startDownload(DOWNLOAD_URL, DOWNLOAD_FILE_NAME);
  }
  private statusColor(): string {
    if (this.status === DownloadStatus.Completed) {
      return '#65E6A7';
    }
    if (this.status === DownloadStatus.Failed || this.status === DownloadStatus.Canceled) {
      return '#FF8C8C';
    }
    if (this.status === DownloadStatus.Paused) {
      return '#FFD166';
    }
    return '#73C7FF';
  }
  private actionLabel(): string {
    if (this.status === DownloadStatus.Downloading) {
      return 'Pause';
    }
    if (this.status === DownloadStatus.Paused) {
      return 'Continue';
    }
    if (this.status === DownloadStatus.Canceled || this.status === DownloadStatus.Failed) {
      return 'Restart';
    }
    if (this.status === DownloadStatus.Completed) {
      return 'Again';
    }
    return 'Download';
  }
  private runPrimaryAction(): void {
    if (this.status === DownloadStatus.Downloading) {
      appWebDownloadService.pauseDownload();
    } else if (this.status === DownloadStatus.Paused) {
      appWebDownloadService.resumeDownload();
    } else if (this.status === DownloadStatus.Canceled || this.status === DownloadStatus.Failed ||
      this.status === DownloadStatus.Completed) {
      appWebDownloadService.restartDownload();
    } else {
      this.startDownload();
    }
  }
  private formatTime(timestamp: number): string {
    const date: Date = new Date(timestamp);
    return `${date.getHours().toString().padStart(2, '0')}:` +
      `${date.getMinutes().toString().padStart(2, '0')}`;
  }
  @Builder
  private header() {
    ArcListItem() {
      Column({ space: 2 }) {
        Text('WEB DOWNLOAD')
          .fontSize(15)
          .fontWeight(FontWeight.Bold)
          .fontColor('#F2F7FF')
        Text(this.page).fontSize(9).fontColor('#73C7FF')
      }
      .width('100%')
      .alignItems(HorizontalAlign.Center)
      .margin({ top: 20, bottom: 2 })
    }
    .height(58)
  }
  @Builder
  private navigation() {
    ArcListItem() {
      Row({ space: 5 }) {
        Button('Download').fontSize(9).height(32).onClick((): void => {
          this.page = AppPage.Download;
        })
        Button('Activity').fontSize(9).height(32).onClick((): void => {
          this.page = AppPage.Activity;
        })
        Button('System').fontSize(9).height(32).onClick((): void => {
          this.page = AppPage.System;
        })
      }
      .width('100%')
      .justifyContent(FlexAlign.Center)
    }
    .height(40)
  }
  @Builder
  private downloadPage() {
    ArcList() {
      this.header()
      ArcListItem() {
        Stack({ alignContent: Alignment.Center }) {
          Progress({ value: this.progressValue, total: 100, type: ProgressType.ScaleRing })
            .width(116)
            .height(116)
            .color(this.statusColor())
            .backgroundColor('#18314B')
          Column({ space: 2 }) {
            Text(`${Math.round(this.progressValue)}%`)
              .fontSize(22)
              .fontWeight(FontWeight.Bold)
              .fontColor('#F2F7FF')
            Text(this.status).fontSize(10).fontColor(this.statusColor())
          }
        }
        .width('100%')
      }
      .height(130)
      .autoScale(true)
      ArcListItem() {
        Column({ space: 3 }) {
          Text(this.fileName.length > 0 ? this.fileName : 'Offline map package')
            .fontSize(11)
            .fontWeight(FontWeight.Medium)
            .fontColor('#E6EEF8')
          Text(this.engineState === EngineState.Attached ? 'Web engine ready' : 'Preparing Web engine…')
            .fontSize(8)
            .fontColor('#8DA4BD')
          if (this.errorMessage.length > 0) {
            Text(this.errorMessage)
              .fontSize(8)
              .fontColor('#FF9E9E')
              .maxLines(2)
              .textAlign(TextAlign.Center)
          }
        }
        .width('82%')
        .padding(8)
        .borderRadius(14)
        .backgroundColor('#10263C')
        .alignItems(HorizontalAlign.Center)
      }
      .height(this.errorMessage.length > 0 ? 70 : 53)
      .autoScale(true)
      ArcListItem() {
        Row({ space: 7 }) {
          Button(this.actionLabel())
            .height(36)
            .fontSize(10)
            .enabled(this.engineState === EngineState.Attached)
            .onClick((): void => this.runPrimaryAction())
          if (this.status === DownloadStatus.Downloading || this.status === DownloadStatus.Paused) {
            Button('Cancel')
              .height(36)
              .fontSize(10)
              .backgroundColor('#7E3040')
              .onClick((): void => appWebDownloadService.cancelDownload())
          }
        }
        .width('100%')
        .justifyContent(FlexAlign.Center)
      }
      .height(50)
      this.navigation()
      ArcListItem() { Text('') }.height(32)
    }
    .width('100%')
    .height('100%')
    .scrollBar(BarState.Off)
    .backgroundColor('#071522')
  }
  @Builder
  private activityPage() {
    ArcList() {
      this.header()
      if (this.records.length === 0) {
        ArcListItem() {
          Column({ space: 6 }) {
            Text('No activity yet').fontSize(14).fontColor('#E6EEF8')
            Text('Finished, canceled, and failed downloads appear here.')
              .fontSize(9)
              .fontColor('#8DA4BD')
              .width('72%')
              .textAlign(TextAlign.Center)
          }
          .width('100%')
          .alignItems(HorizontalAlign.Center)
        }
        .height(115)
      }
      ForEach(this.records, (record: DownloadActivityRecord) => {
        ArcListItem() {
          Column({ space: 3 }) {
            Row() {
              Text(record.title).fontSize(10).fontColor('#E6EEF8').layoutWeight(1).maxLines(1)
              Text(this.formatTime(record.createdAt)).fontSize(8).fontColor('#71869D')
            }
            .width('100%')
            Row() {
              Text(record.status).fontSize(9).fontColor('#73C7FF').layoutWeight(1)
              Text(`${Math.round(record.progress)}%`).fontSize(9).fontColor('#A9BDD1')
            }
            .width('100%')
            if (record.errorMessage.length > 0) {
              Text(record.errorMessage).fontSize(8).fontColor('#FF9E9E').maxLines(1).width('100%')
            }
          }
          .width('82%')
          .padding(9)
          .borderRadius(15)
          .backgroundColor('#10263C')
        }
        .height(record.errorMessage.length > 0 ? 70 : 56)
        .autoScale(true)
      }, (record: DownloadActivityRecord): string => record.id)
      if (this.records.length > 0) {
        ArcListItem() {
          Button('Clear activity').height(34).fontSize(9)
            .onClick((): void => appWebDownloadService.clearActivity())
        }
        .height(45)
      }
      this.navigation()
      ArcListItem() { Text('') }.height(32)
    }
    .width('100%')
    .height('100%')
    .scrollBar(BarState.Off)
    .backgroundColor('#071522')
  }
  @Builder
  private systemPage() {
    ArcList() {
      this.header()
      ArcListItem() {
        Column({ space: 8 }) {
          Text(this.engineState === EngineState.Attached ? '✓' : '…')
            .fontSize(34)
            .fontColor(this.engineState === EngineState.Attached ? '#65E6A7' : '#FFD166')
          Text(`Web Engine: ${this.engineState}`)
            .fontSize(13)
            .fontWeight(FontWeight.Bold)
            .fontColor('#F2F7FF')
          Text(this.engineState === EngineState.Attached ?
            'System is running and healthy' : 'Waiting for controller attachment')
            .fontSize(9)
            .fontColor('#8DA4BD')
        }
        .width('82%')
        .padding({ top: 16, bottom: 16 })
        .borderRadius(22)
        .backgroundColor('#10263C')
        .alignItems(HorizontalAlign.Center)
      }
      .height(142)
      .autoScale(true)
      this.navigation()
      ArcListItem() { Text('') }.height(32)
    }
    .width('100%')
    .height('100%')
    .scrollBar(BarState.Off)
    .backgroundColor('#071522')
  }
  build() {
    Stack() {
      if (this.page === AppPage.Download) {
        this.downloadPage()
      } else if (this.page === AppPage.Activity) {
        this.activityPage()
      } else {
        this.systemPage()
      }
      DownloadEngineHost()
    }
    .width('100%')
    .height('100%');
  }
}

Run the sample

Build and run the application on a wearable device or emulator that provides SystemCapability.Web.Webview.Core. Open the System page first and confirm that the engine state is Attached. Return to Download, start the transfer, and verify the Downloading, Paused, Canceled, Completed, and Activity states through the real ArkWeb callbacks.

Testing and Results

The implementation was validated as an application, not only as isolated code. The project was clean-built with HarmonyOS 6.1.1 API 24 SDK, installed on a wearable emulator, and operated through the real interface. A public 50 MB response was used for the completion run.

• Clean build: assembleHap completed without ArkTS compiler errors or ArkTS code warnings.
• Environment: HarmonyOS 6.1.1 API 24 wearable emulator, 466 x 466 display.
• Engine setup: onControllerAttached completed and the System page reported Attached.
• Lifecycle: start, progress, pause, continue, cancel, restart, finish, and failure paths were exercised.
• File verification: offline_map.bin existed in the application files directory at exactly 50,000,000 bytes.
• UI verification: ring state, action labels, terminal state, and activity history matched the callbacks.

The displayed completion state corresponds to a real file written by ArkWeb, not to a simulated progress timer. The produced HAP remained unsigned because the Empty Ability project did not include a signing profile; the wearable emulator accepted the debug artifact.

Why this design is practical

• The Web engine lifecycle is isolated from visible page navigation.
• The page is a renderer and command surface, not the owner of transfer truth.
• A single snapshot makes UI transitions deterministic and easy to inspect.
• Cancellation intent is preserved across ArkWeb callback semantics.
• The destination is predictable, private, and safe to replace for a restart.

Limitations and Production Considerations

One active transfer

The singleton stores one active WebDownloadItem. Starting another transfer replaces the displayed URL, destination, flags, and item reference. A multi-download product should maintain a map keyed by item GUID and expose a collection of snapshots.

Session-only history and recovery

Activity records are kept in memory, and the active item is not serialized. The official ArkWeb guide documents serialization and WebDownloadManager.resume Download for recovery after process exit. Add persistence only when the product needs that lifecycle; do not imply recovery when it is not implemented.

Background execution

This sample does not request a continuous background-task mode. Behavior after the ability moves to the background or the process terminates is outside its guarantee. A production requirement for long-running background downloads must be designed and tested separately.

Storage visibility and integrity

filesDir is app-private. A user-visible export needs a picker or sharing flow. Production code should define free-space checks, filename sanitization, expected size or checksum validation, cleanup, and retention rules. The sample deletes an existing same-name file before starting again.

Network and progress behavior

The server controls transfer speed and resumability. A small response can finish before Pause is tapped. getPercentComplete can return -1 when progress is unknown. The demo endpoint is suitable for testing only; production should use an owned HTTPS endpoint with explicit retry and integrity policy.

Conclusion

A reliable Web Download Manager on HarmonyOS NEXT is less about drawing a progress ring and more about respecting ownership. ArkWeb owns the transfer lifecycle. The service translates that lifecycle into explicit application state. ArkUI renders the state and sends guarded commands back to the service.

Once those boundaries are clear, pause, continue, cancel, restart, completion, and activity tracking become small, understandable operations. The same pattern can scale beyond wearables: a phone or tablet UI may render more metadata, and a production service may persist serialized tasks or manage concurrent items, but the core rule remains the same, build the interface from verified callback state, not from assumptions.

Key takeaway: Keep the Web component mounted, wait for controller attachment, register one verified delegate, treat WebDownloadItem as the control handle, and let a state-driven service be the single source of truth for the UI.

Related Resources and References

1. Huawei Developers: Downloading Files with ArkWeb
2. Huawei Developers: WebviewController reference
3. Huawei Developers: WebDownloadDelegate reference
4. Huawei Developers: WebDownloadItem reference
5. Huawei Developers: Web component events
6. Huawei Developers: File management APIs
7. Huawei Developers: ArkTS declarative UI description

Building a Web Download Manager with ArkWeb on HarmonyOS NEXT was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

A watch with 5.9 GB of storage reports 5.3 GB free. Where did the other 0.6 GB go, and how much of it belongs to your app?

The ticket sounded simple: add a storage screen to a wearable app. It turned out to be three problems. HarmonyOS answers each one with a different API, and each API has its own return shape and availability rules.

This guide shows how to measure free space, app footprint and per-folder usage on HarmonyOS with ArkTS (the TypeScript-based language for HarmonyOS apps). It uses the Core File Kit, specifically statfs, storageStatistics and fileIo. The examples come from a sample project: one entry module, API 21, targeting phone and wearable.

Three questions, three APIs

• How much space is left on the device? Use statfs.getFreeSize() and statfs.getTotalSize().
• How much of it does this app use? Use storageStatistics.getCurrentBundleStats().
• Which folders are growing? Use fileIo.listFile() and fileIo.stat(), walked recursively.

Each API has a trap. Knowing them up front saves a lot of debugging.

Trap 1: there is no “used space” API. statfs returns total and free size only. You compute used space as total - free.

Trap 2: storageStatistics may not exist on the device. It depends on SystemCapability.FileManagement.StorageService.SpatialStatistics, which a wearable is not required to declare. An unguarded call compiles but fails at runtime.

Trap 3: the system figure does not say where the space went. getCurrentBundleStats() returns one number per category. That works for a summary but not for deciding what to delete.

Trap 4: a naive recursive walk can hang or over-count. Directory sizes inflate the total, a symlink can cause an endless loop, and one unreadable file can abort the whole measurement.

Background

statfs (from @kit.CoreFileKit) wraps the POSIX statvfs call. It reports on the file system a path belongs to, not on a physical disk, so the path you pass decides the result. A normal app can only query paths it can read. Pass context.filesDir, which on a wearable sits on the user data partition. That is the figure a free-space screen should show.

storageStatistics returns a BundleStats object for the calling app:

• appSize: installation files (/data/storage/el1/bundle)
• cacheSize: cache directories
• dataSize: user data excluding the two above (base, database, distributedfiles)

Querying your own bundle needs no permission. The other variants, getBundleStats(bundleName), getFreeSizeOfVolume and volumeManager, are restricted to system apps.

fileIo provides listFile and stat. For a regular file, Stat.size is the byte count. For a directory, it is the size of the inode record (the file system's metadata entry), not the size of its contents. This matters in Step 4.

Step 1: Define shared data models

The three APIs return unrelated shapes: two numbers, a BundleStats object and a tree you build by hand. I defined common models in model/StorageModels.ets: DeviceSpace, AppSpace, DirUsage and StorageSnapshot. An EmptyStorage factory gives the UI something to render before the first query returns.

AppSpace.available is false when the device lacks SpatialStatistics. The UI then shows -- instead of 0 B. 0 B would claim the app uses no space, while -- correctly says the value is unknown.

Pro Tip: Model “unavailable” explicitly. A flag like available costs one field and prevents the UI from showing a wrong number.

Step 2: Read total and free space with statfs

import { statfs } from '@kit.CoreFileKit';

static async read(context: common.UIAbilityContext, path?: string): Promise<DeviceSpace> {
  const target: string = path ?? context.filesDir;
  const sizes: number[] = await Promise.all([
    statfs.getTotalSize(target),
    statfs.getFreeSize(target)
  ]);
  return {
    totalBytes: sizes[0],
    freeBytes: sizes[1],
    // statfs has no "used" call - used space is simply what is not free.
    usedBytes: Math.max(0, sizes[0] - sizes[1]),
    measuredPath: target
  };
}

Synchronous variants exist (getTotalSizeSync, getFreeSizeSync). Avoid them in aboutToAppear. They block the UI thread, and they throw instead of rejecting, so they need their own try/catch.

Step 3: Read app footprint behind a capability guard

import { storageStatistics } from '@kit.CoreFileKit';

static async read(): Promise<AppSpace> {
  // The capability check has to appear literally here: the compiler does not accept
  // a boolean field holding the result of canIUse as a guard.
  if (canIUse('SystemCapability.FileManagement.StorageService.SpatialStatistics')) {
    try {
      const stats: storageStatistics.BundleStats = await storageStatistics.getCurrentBundleStats();
      return {
        appSize: stats.appSize,
        cacheSize: stats.cacheSize,
        dataSize: stats.dataSize,
        totalSize: stats.appSize + stats.cacheSize + stats.dataSize,
        available: true
      };
    } catch (error) {
      return EmptyStorage.app();          // available: false
    }
  }
  return EmptyStorage.app();              // capability absent - fall back to the walk
}

A missing capability should not break the whole screen. If the module is absent, return an “unavailable” result and let the rest of the page render.

canIUse must appear literally at the call site

Caching the result in a field looks like good practice:

private hasSpatial: boolean = canIUse('SystemCapability....');  // does not work as a guard

It compiles, but every guarded call then reports “The API is not supported on all devices.” The compiler only recognises a literal canIUse call as a guard. The same applies to helper methods that construct guarded objects. Repeat the capability string at each call site.

Pro Tip: Do not wrap canIUse in a helper or a constant. It feels like duplication, but the compiler requires the literal call.

Step 4: Walk the sandbox directories

Totals show how much space is used. Only a walk shows where. common/DirectorySizer.ets drives the recursion one level at a time, so each child directory gets its own byte count:

import { fileIo } from '@kit.CoreFileKit';

const entries: string[] = await fileIo.listFile(path);      // one level only
for (const entry of entries) {
  const childPath: string = `${path}/${entry}`;
  const stat: fileIo.Stat = await fileIo.stat(childPath);
  if (stat.isDirectory()) {
    if (maxDepth <= 0) { totals.errorCount++; continue; }   // depth budget spent
    const child: DirUsage = await DirectorySizer.measure(childPath, entry, maxDepth - 1);
    node.children.push(child);
    // ...fold child totals into this node
  } else {
    totals.sizeBytes += stat.size;                          // only regular files add bytes
    totals.fileCount++;
  }
}
node.children.sort((a: DirUsage, b: DirUsage) => b.sizeBytes - a.sizeBytes);

Four rules shape this code:

1. Only regular files add bytes. A directory’s Stat.size is its inode record. Adding it inflates the total.
2. Cap the recursion depth. The sample uses 16. A symlink loop would otherwise never finish. Entries beyond the cap go into errorCount instead of being silently reported as zero.
3. Count failures, do not abort. Files can disappear during a walk on a live device. A missing directory is also normal: a fresh install has no databaseDir until something writes to it.
4. Keep everything async. A sandbox walk is real I/O (disk input and output) and must stay off the UI thread.

Why not listFile with recursion?

listFile can recurse by itself:

const options: ListFileOptions = { recursion: true, listNum: 0 };
const entries: string[] = await fileIo.listFile(path, options);  // every descendant, one call

This is shorter, but it returns a flat list with no per-directory attribution and no depth control. Each entry still needs a stat call. A cleanup screen needs to know which folder grew, so the sample drives the recursion itself.

ListFileOptions is a top-level export of the kit, not a member of the fileIo namespace.

Step 5: Run the sources concurrently

StorageViewModel starts all three sources at once. A refresh then takes as long as the slowest source, not the sum of all three:

const devicePromise: Promise<DeviceSpace> = DeviceStorage.read(context);
const appPromise: Promise<AppSpace> = BundleStorage.read();
device = await devicePromise;
app = await appPromise;

const walks: Promise<DirUsage>[] = StorageViewModel.sandboxRoots(context)
  .map((root: SandboxRoot) => DirectorySizer.measure(root.path, root.name));
roots = await Promise.all(walks);
roots.sort((a: DirUsage, b: DirUsage) => b.sizeBytes - a.sizeBytes);

sandboxRoots() covers filesDir, cacheDir, tempDir, preferencesDir and databaseDir, and skips any the context does not expose. The snapshot also records elapsedMs, which shows what the walk costs.

The view model never throws. A failed source appears as zeroed figures in the snapshot instead of crashing the screen.

Step 6: Format bytes in one place

These APIs return raw numbers such as 12582912. ByteFormatter is the single place that converts them, using binary units (1 KB = 1024 B):

• formatBytes(bytes, decimals = 2): 1536 → 1.50 KB. Used for full-width readouts.
• formatBytesShort(bytes): 12582912 → 12 MB. Used for watch rows, which have room for about six characters.
• percent(part, whole): (1, 4) → 25. Used for the ring gauge value.
• formatPercent(part, whole): (3, 4) → 75%. Used for the "x% used" caption.

Invalid input returns -- instead of NaN or undefined. percent clamps to 0–100 and maps a zero whole to 0, because a gauge given NaN does not draw.

On the wearable, the page renders the snapshot as three full-screen cards in an ArcSwiper, with ArcList rows and an ArcButton to refresh. This is gated by canIUse('SystemCapability.ArkUI.ArkUI.Circle'), so phones fall back to a plain Swiper and List.

Result on a wearable

Build against compatibleSdkVersion 6.0.1 (API 21) and run on a wearable emulator or device. Then swipe through the three cards.

The Device card should show non-zero total and free values. That confirms statfs resolved the sandbox path.

The App card shows install, data, cache and total. If every row shows --, SpatialStatistics is absent on that device. That is expected, not a bug.

The Sandbox card lists directories sorted largest-first, with a walked total. This sample was freshly installed, so its sandbox is nearly empty.

Pro Tip: The App total can exceed the walked total, and that is correct. The system figure includes the installed HAP (HarmonyOS Ability Package), which lives outside the sandbox. Show both numbers instead of hiding the gap.

Limitations

• statfs measures a file system, not a disk. Pass a path the app can read, or a non-system app gets an error.
• getBundleStats(bundleName), getFreeSizeOfVolume and volumeManager are system-app only. A normal app can query only its own bundle.
• The walk costs real I/O that grows with file count. Keep it async, keep the depth cap, and do not run it on every frame.
• Arc components need API 18 or later and SystemCapability.ArkUI.ArkUI.Circle. Phones do not have them.

Troubleshooting

My walked total is far larger than the device reports. You are probably adding directory sizes. Add bytes only where stat.isDirectory() is false.

Can I use storageStatistics.getTotalSize() instead of statfs? Yes, from API 15, with no path argument. I used statfs because it is per file system, works on earlier API levels, and falls under the widely available FileManagement.File.FileIO capability.

The rows on my watch stay at their first values while the gauge keeps updating. Both causes are in the render layer, not storage. First, a @Builder with by-value parameters is evaluated once and does not re-run when @State changes. Render rows through a child @Component with @Prop instead. Second, ForEach reuses any item whose key has not changed, so make the key include the value: `${item.key}#${item.value}`.

Conclusion

Monitoring storage on HarmonyOS means combining three APIs, not choosing one. Use statfs for the device, getCurrentBundleStats() for the app, and a depth-capped fileIo walk for folders. Guard capability-dependent calls with a literal canIUse, and show -- instead of 0 B when data is unavailable. Run all sources concurrently into one snapshot that never throws, and show both totals, because they measure different things.

What would you add to a storage screen on a wearable: a cleanup action, a history graph, or per-file details? Share your ideas in the comments.

References

• ArkTS APIs Core File Kit
• @ohos.file.statvfs (statfs)
• @ohos.file.storageStatistics
• @ohos.file.fs (fileIo)
• Accessing Application Files (ArkTS)
• Application Sandbox Directory
• Sharing an Application File
• SystemCapability and canIUse
• APIs No Longer Maintained Core File Kit
• ArkTS Components ArkUI
• ArcListItem
• Arc Button (ArcButton)
• ArkUI About This Kit

How to Measure Storage on HarmonyOS in 2026? was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

Getting a workout onto the watch is only half the job. You applied for Huawei Health Kit access as a HarmonyOS app, wired up Workout Service in your wearable app, and finished workouts now show up nicely in the Huawei Health app. Then the next step comes up: getting those same workouts into your own app.

Here’s what that usually turns into:

• Wondering if cloud access needs a whole new application
• Hunting for a clientID and clientSecret you never explicitly created
• Not knowing where the callback URL is supposed to live now
• Guessing which scope actually covers workout records

What I wanted was one clear path: take the HarmonyOS permission I already had and use it to read workout records from Health Cloud in my own app.

One Application Is Enough

Good news first: you don’t need a second application. Health Cloud works exactly the same way it always has. The only thing that changes is where you pick up the clientID, the clientSecret and the callback URL for the initial setup.

Once those three values are in place, everything else is the standard Health Kit cloud authorization flow. No extra configuration, no special case for HarmonyOS apps.

Finding Your Credentials in AGC

Everything lives in one place: AGC > Development and Services > App. AGC generates the clientID and clientSecret automatically when you create the app, so they’re already waiting for you there.

If your app has server to server permission, you probably added your callback URL earlier through Huawei Developer Console > HUAWEI ID > App > Callback URL. Here you just enter that same callback URL in the Callback URL field on the AGC app page, and the configuration is done.

Building the Authorization URL

Next, build the authorization URL. It points to the HUAWEI ID authorization endpoint at https://oauth-login.cloud.huawei.com/oauth2/v3/authorize and carries three things:

• The clientID from AGC
• The callback URL you configured in AGC
• The health data permissions you’re asking for, in the scope parameter

To read workout records saved with Workout Service, the activityrecord.read permission (https://www.huawei.com/healthkit/activityrecord.read) is all you need in the scope.

Getting the Authorization Code

Open the URL for the user. They sign in with their HUAWEI ID and review the permissions you’re requesting. Once they grant them, HUAWEI ID redirects to your callback URL with an authorization code attached.

Trading the Code for an Access Token

Now exchange that code for an access token. Send a POST request to the token endpoint at https://oauth-login.cloud.huawei.com/oauth2/v3/token with:

• grant_type set to authorization_code
• The code you just received
• Your clientID and clientSecret
• redirect_uri, set to your callback URL

The response includes an access token and, if you requested one, a refresh token.

Querying Workout Records

Finally, put the access token in the Authorization header as a Bearer token and call the Health Kit REST APIs. From here you can query whatever you need, like workout records within a specific time range.

Wrapping Up

Your existing HarmonyOS Health Kit permission already gets you into Health Cloud: collect the credentials from AGC and run the usual authorization flow.

Here’s what it buys you:

• No second application to submit
• clientID and clientSecret generated for you in AGC
• The same callback URL you already use carries over
• One scope, activityrecord.read, is enough for workout records
• Everything after setup is the cloud flow you may already know

Where it doesn’t fit:

• The token exchange uses your clientSecret, so it needs to happen somewhere you control, like your own server
• Reading data always starts with the user signing in and approving through HUAWEI ID, so there’s no silent access before that first consent

Happy coding! 😊

References

• Document
• Document

How Do You Read Wearable Workouts in Your Own App Without a Second Health Kit Application? was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

DevEco Studio is excellent for day-to-day development, but continuous integration and continuous delivery (CI/CD) pipelines do not have a graphical user interface, and they should not depend on one. A build agent running GitLab CI, GitHub Actions, or Jenkins needs a headless path from source code to a signed artifact that is ready for installation on a device.

The HarmonyOS Command Line Tools (CLI tools) ship with everything a pipeline needs: Hvigor as the build engine, ohpm (OpenHarmony Package Manager) for dependencies, hdc (HarmonyOS Device Connector) for device communication, and hap-sign-tool for signing. Combined with the standard Java keytool, you can generate keystores, Certificate Signing Requests (CSRs), digital certificates, and provisioning profiles entirely from the terminal.

In this tutorial we walk through installing the toolchain, compiling HarmonyOS Ability Packages (HAPs) and application bundles (APPs), running the result on a real watch, and automating production signing on Linux.

Why a Headless Build Pipeline Matters

Every manual step in a release process is a place where a human can make a mistake. Renaming a file, remembering the correct product name, or copying the right certificate into the right folder are all small actions that become expensive when they fail on a Friday release.

A headless workflow solves three concrete problems:

1. Reproducibility. The same commands run in the same order produce the same artifacts, whether they are executed on a developer laptop or on a build agent.
2. Automation. Once compilation and signing are scripted, a Git tag can trigger a full release build without anybody opening DevEco Studio.
3. Security. Credentials live in a secret store instead of a developer’s home directory, and signing keys are never typed into an interactive dialog where they can end up in a shell history file.

Setting Up the Headless Environment

Start with the foundation: Java. HarmonyOS tooling expects Java Development Kit (JDK) 17, and the simplest approach is to unpack a distribution such as jdk-17.0.6_linux-x64_bin.tar.gz into /opt and point the environment at it.

export JAVA_HOME=/opt/jdk-17.0.6
export PATH=$JAVA_HOME/bin:$PATH
java -version   # verify JDK 17 is installed

Next, download the Command Line Tools package from the Huawei Developer portal and unzip it. Setting a single root variable keeps every later path short and portable across machines.

unzip command-line-tools.zip
export COMMANDLINE_TOOL_DIR=/opt

This produces ${COMMANDLINE_TOOL_DIR}/command-line-tools. Do not rename that folder, several internal scripts resolve paths relative to it.

The suite bundles its own Node.js runtime. Always prefer the bundled copy over the one installed by your distribution, because version skew between Node.js and Hvigor is a common source of obscure build failures.

export NODE_HOME=$COMMANDLINE_TOOL_DIR/command-line-tools/tool/node
export PATH=$NODE_HOME/bin:$PATH
node -v   # should show Node.js (v18+ recommended)

Then add the device connector and the build/package managers to the path. hdc lives in the OpenHarmony toolchains folder, while hvigorw and ohpm sit in the tools' bin directory.

export HDC_HOME=$COMMANDLINE_TOOL_DIR/command-line-tools/sdk/default/openharmony/toolchains
export PATH=$HDC_HOME:$PATH
export PATH=$COMMANDLINE_TOOL_DIR/command-line-tools/bin:$PATH
hvigorw -v   # should print the Hvigor version
ohpm -v      # should print the Ohpm version

Checklist before you continue: JAVA_HOME, NODE_HOME, HDC_HOME, and COMMANDLINE_TOOL_DIR must all be defined, and PATH must include $JAVA_HOME/bin, $NODE_HOME/bin, command-line-tools/bin, and openharmony/toolchains.

Pro Tip: Store all of these exports in a single env.sh file and source it at the top of your pipeline script. Duplicated environment setup is the number one reason a build passes locally and fails on the agent.

Building the Project with Hvigor

HarmonyOS uses Hvigor as its build engine, and all tasks are driven through the ./hvigorw script. The two flags you will use constantly are --mode, which selects module-level or project-level assembly, and -p product=<name>, which chooses the product flavor declared in your build profile.

For day-to-day validation, compile all HAP modules without applying a production signature:

hvigorw assembleHap --mode module -p product=default \
-p buildMode=debug --no-daemon

To produce a complete .app bundle that contains every module and is ready for release signing:

hvigorw assembleApp --mode project -p product=default \
-p buildMode=release --no-daemon

And to purge previous caches and output directories when a build starts behaving strangely:

hvigorw clean --no-daemon

All compiled artifacts (.hap, .har, .app) land in the build/ directory of the corresponding module, or in the root build/ folder for project-level output. On a CI agent, hvigorw clean before every release build is cheap insurance against stale incremental state.

Why --no-daemon? The Hvigor daemon keeps a process alive between invocations to speed up interactive use. Build agents run one build and then throw the container away, so the daemon adds nothing but a leftover process that can hold a port. Always disable it in pipelines.

Directory tree showing build/ output

<project-root>/
├── build/
│   └── outputs/
│       └── default/
│           ├── <project-name>-default-signed.app
│           └── <project-name>-default-unsigned.app
└── entry/
    └── build/
        └── default/
            └── outputs/
                └── default/
                    ├── entry-default-signed.hap
                    └── entry-default-unsigned.hap

Generating the Signing Chain from the Terminal

Signing a HarmonyOS application requires a four-file chain: a keystore (.p12), a Certificate Signing Request (.csr), a digital certificate (.cer), and a provisioning profile (.p7b). Miss one link and the device will refuse to install your package.

Step 1 - Key pair and keystore (.p12)

Use the standard Java keytool with an elliptic curve (EC) key on the secp256r1 curve:

keytool -genkeypair -alias "my_app_alias" \
-keyalg EC -groupname secp256r1 -sigalg SHA256withECDSA \
-dname "C=CN,O=HUAWEI,OU=HUAWEI IDE,CN=demo_key" \
-keystore "my_app_key.p12" -storetype PKCS12 \
-validity 9125 \
-storepass "KeystorePassword123" \
-keypass "KeystorePassword123"

A few details matter more than they look. CN should match the alias, because some verification paths compare them. validity is expressed in days, 9125 is roughly 25 years. And storepass must contain at least 8 characters using at least two of the following classes: uppercase letters, lowercase letters, digits, and special characters.

Step 2 - Certificate Signing Request (.csr)

The CSR is what proves you own the private key without revealing it:

keytool -certreq -alias "my_app_alias" \
-sigalg SHA256withECDSA \
-keystore "my_app_key.p12" -storetype pkcs12 \
-file "my_app.csr"

Step 3 -Certificate (.cer) and profile (.p7b)

• Upload my_app.csr to AppGallery Connect in the Huawei Developer Console
• Download the generated application certificate (my_app.cer)
• Register the Unique Device Identifiers (UDIDs) of your test watches, create an App Provisioning Profile
• Download the resulting .p7b file

Pro Tip: For a wearable, forgetting to register a device UDID is the single most common reason a correctly signed HAP is rejected. Keep a scripted list of test watches and refresh the provisioning profile whenever that fleet changes.

Signing an Unsigned HAP File

After a debug build with assembleHap, you get an entry-default-unsigned.hap. The signing tool operates on the raw binary inside that package, so the process is a short unpack–sign–repack cycle.

Change the extension of the -unsigned.hap file to .zip, extract the .bin file contained in the archive, then run the signing tool:

java -jar hap-sign-tool.jar sign-app \
-keyAlias "demo_key" -signAlg "SHA256withECDSA" -mode "localSign" \
-appCertFile "/path/demo.cer" -profileFile "/path/demo.p7b" \
-inFile "/path/entry-default-unsigned.bin" \
-keystoreFile "/path/demo.p12" \
-outFile "/path/entry-default-signed.bin" \
-keyPwd "123456Abc" -keystorePwd "123456Abc" -inForm bin

• Execute the command from ${COMMANDLINE_TOOL_DIR}/command-line-tools/sdk/default/openharmony/toolchains/lib.
• Then archive the newly generated .bin back into a .zip, revert the extension to .hap, and continue with the deployment steps below.

Running an App

Use hdc to push a signed HAP to a real device for installation. Note that if the pushed HAP is not signed, the installation will fail, this is exactly why the four-file signing chain comes first in the pipeline.

Note: hdc is not supported on lite wearable devices (GT, FIT, D, and Runner series). Therefore, this step does not apply to these devices.

To push a HAP, run the following commands

# Push the HAP to the device.
hdc file send "{PROJECT_PATH}/entry/build/default/outputs/default/entry-default-signed.hap" "data/local/tmp/entry-default-signed.hap"
# Install the HAP.
hdc shell bm install -p "data/local/tmp/entry-default-signed.hap"
# Delete the HAP.
hdc shell rm -rf "data/local/tmp/entry-default-signed.hap"

To run the HAP on the device, run the following command:

hdc shell aa start -a EntryAbility -b com.example.myapplication -m entry

Replace com.example.myapplication with your own bundle name and EntryAbility with the ability you want to launch.

More details about hdc are available in the official documentation: https://developer.huawei.com/consumer/en/doc/harmonyos-guides/hdc

Signing a Release APP File

The release path is conceptually simpler: a project-level build already assembles everything into a single bundle.

hvigorw assembleApp --mode project -p product=default \
-p buildMode=release --no-daemon

Then sign app-unsigned.app

java -jar hap-sign-tool.jar sign-app \
-keyAlias "demo_key" -signAlg "SHA256withECDSA" -mode "localSign" \
-appCertFile "/path/demo.cer" -profileFile "/path/demo.p7b" \
-inFile "/path/app-unsigned.app" \
-keystoreFile "/path/demo.p12" \
-outFile "/path/app-signed.app" \
-keyPwd "$KEY_PWD" -keystorePwd "$KEYSTORE_PWD"

Run it from the same toolchains/lib directory. In a pipeline, pass the passwords through environment variables sourced from your CI secret store rather than hard-coding them in the command.

Pro Tip: Signing is not encryption. The private key stays in the keystore. That means rotating a certificate is a pipeline configuration change, not a code change, so design your scripts to accept certificate paths as parameters from day one.

Common Mistakes to Avoid

• Mixing up --mode module and --mode project. Debug HAPs come from module mode; release bundles come from project mode. Using the wrong one produces an artifact that cannot be signed the way you expect.
• Using the system Node.js. Always export NODE_HOME pointing at the bundled runtime.
• Forgetting to revert the .zip extension. A signed binary with the wrong extension will not install.
• Running hap-sign-tool.jar from an arbitrary directory. Relative resource loading fails silently in some versions.
• Different storepass and keypass. The signing tool requires them to match.
• Committing the .p12 keystore to version control. Treat it like a production credential, never like an asset.

Putting It All Together: An Example Pipeline Script

The sections above become far more useful when they are stitched into a single script that a CI agent can execute from top to bottom. The following example initializes the JDK, the device connector, and ohpm, builds the HAP and installs it on a connected device.

#!/bin/bash
set -ex

JAVA_HOME=xxx # Specify the installation directory of the JDK.
COMMANDLINE_TOOL_DIR=xxx # Specify the installation directory of the command line tool.

# Configure the hvigor and ohpm environment variables.
export PATH=${COMMANDLINE_TOOL_DIR}/command-line-tools/bin:$PATH

# Download and configure JDK.
function init_JDK() {
  if [ ! -d "${JAVA_HOME}" ]; then
     mkdir "${JAVA_HOME}"
  fi
  cd ${JAVA_HOME}
  wget --no-check-certificate -q "${jdk_download_path}" -O jdk-linux.tar.xz # Download JDK, specifying the actual download path.
  tar -vxf jdk-linux.tar.xz
  JDK_DIR=xxx # Specify the directory in the compressed JDK package.
  cd ${JDK_DIR}
  mv -f ./* .[^.]* ../
  cd ..
  rm -rf JDK_DIR jdk-linux.tar.xz
  export JAVA_HOME=${JAVA_HOME}
  export PATH=$JAVA_HOME/bin:$PATH
  java -version
}

# Configure the hdc environment variable.
function init_hdc() {
  export HDC_HOME=${COMMANDLINE_TOOL_DIR}/command-line-tools/sdk/default/openharmony/toolchains # Set the hdc environment variable. hdc is stored in toolchains.
  export PATH=$HDC_HOME:$PATH
}

# Install ohpm. Skip this step if ohpm already exists in the image.
function init_ohpm() {
    ohpm -v
    # Configure the address of the ohpm repository.
    ohpm config set registry https://ohpm.openharmony.cn/ohpm/
}

# Initialize related paths.
PROJECT_PATH=xxx  # Project directory.
# Go to the package directory and install the dependency.
function ohpm_install {
    cd $1
    ohpm install
}
# Environment adaptation
function buildHAP() {
# Install the third-party library dependencies based on service requirements.
    ohpm_install "${PROJECT_PATH}"
    ohpm_install "${PROJECT_PATH}/entry"
    ohpm_install "${PROJECT_PATH}/xxx"
    # Run commands based on your service requirements. For details, see the commands in the DevEco Studio build log.
    cd ${PROJECT_PATH}
    hvigorw clean --no-daemon
    hvigorw assembleHap --mode module -p product=default -p debuggable=false --no-daemon # It is recommended that --no-daemon be added to the end of the command.
}
function install_hap() {
    hdc file send "${PROJECT_PATH}/entry/build/default/outputs/default/entry-default-signed.hap" "data/local/tmp/entry-default-signed.hap"
    hdc shell bm install -p "data/local/tmp/entry-default-signed.hap"
    hdc shell rm -rf "data/local/tmp/entry-default-signed.hap"
    hdc shell aa start -a MainAbility -b com.example.myapplication -m entry
}

function main {
  local startTime=$(date '+%s')
  init_JDK
  init_hdc
  init_ohpm
  buildHAP
  install_hap
  local endTime=$(date '+%s')
  local elapsedTime=$(expr $endTime - $startTime)
  echo "build success in ${elapsedTime}s..."
}
main

NOTE: The following example is not ready for direct use. Adapt it to meet your specific requirements.

Pro Tip: Extend the script with a signing step between buildHAP and install_hap, reading the keystore password from an environment variable. That keeps the entire release path: compile, sign, install, in one auditable file.

Conclusion

A fully GUI-less HarmonyOS build and signing workflow on Linux is not only possible. It is the most reliable way to release a HarmonyOS application repeatedly. By installing the CLI tools, exporting a consistent environment, driving Hvigor with the correct mode and product parameters, automating the four-file signing chain through keytool and hap-sign-tool, and deploying the result with hdc, you remove every manual step between a commit and a running app on a watch.

References

• Document
• Document
• Document

How to Build, Sign and Run HarmonyOS Apps via Linux CLI was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learn why the Wear Engine application form shows “No available product for service release” and how to fix it

Introduction

Wear Engine is the Huawei service used for app-to-app messaging between the Android companion app on your phone and the app on your wearable device, such as a Huawei Watch GT series or Watch Fit series. It lets the two sides send messages, transfer data, and stay in sync.

Using the service requires submitting an application through your HUAWEI Developers account, and that submission form. However, when this application form is accessed and the application type is selected, the warning “No available product for service release” is displayed on the selection element.

Understanding The Problem

This prerequisite exists for a good reason. Wear Engine needs to know in advance which application is allowed to talk to which wearable, and which identity the phone-side app should use during messaging. If the identity and service behind that account are not enabled, there is literally nothing the form can list, hence “no available product.”

How To Handle It

In practice, the error traces back to one of three structural causes:

Fix 1: Apply for and Configure the HUAWEI ID Service.

The most common trigger is the simplest one to miss: the HUAWEI ID service has not been applied for, or has not been fully configured.

Head to the Management Center in the HUAWEI Developers console, click HUAWEI ID, and apply for it.

Two checks matter here. First, verify whether your existing application is correctly linked to the Developer Console through the Huawei ID service. Second, if it is not, create the application directly through this service.

For detailed instructions, refer to the official guide “Registering a HUAWEI ID and Applying for the HUAWEI ID Service” listed in the References section at the end. Follow it in order, and you close off the first failure mode completely.

Fix 2: Enable the Account Kit Service in AppGallery Connect.

You can have a perfectly registered HUAWEI ID and still see the error, because the identity alone is not enough.

Wear Engine also depends on Account Kit, the service that lets users sign in with their HUAWEI ID inside your app. If Account Kit is switched off, the Wear Engine form still finds nothing to offer.

To check it, follow these steps:

• Log in to AppGallery Connect.
• Access your project through the “Development and services” page.
• Select your specific app and open the “Manage APIs” tab.
• Verify whether Account Kit is enabled. If it is not, switch it on.

Fix 3: Recheck Your Application and Project Setup

If your identity is complete and Account Kit is enabled, the remaining cause is the application object itself. Two variations of this problem are common, and they are easy to confuse with each other.

The application was never created: You may have set up a project on AppGallery Connect without initializing a corresponding application inside it.

Sign in to AppGallery Connect, select your project, and check whether an application actually exists under it. If there is no app, create one first. The Wear Engine form can only list existing products, an empty project offers it nothing.

The platform does not match: The application may exist, but its platform type might not match the platform selected in your Wear Engine application form.

Open the project and inspect the platform configuration. If the required platform does not exist, create a new application for that platform within the same project, rather than trying to edit the existing one.

Pro Tip: Create the application directly through the HUAWEI ID service in the Developer Console, instead of creating a project first and linking the identity afterwards. This single habit eliminates the two most common failure modes

Conclusion

The “No available product for service release” error is a setup problem. It appears whenever the identity behind your account, the Account Kit service, or the application object itself falls out of alignment. Resolving it means finishing the HUAWEI ID service setup, enabling Account Kit in AppGallery Connect, and verifying that your application and its platform exist and match.

Start by creating the application through the HUAWEI ID flow, and most of these pitfalls disappear. Have you hit this error while connecting your phone and wearable, and which of the three causes turned out to be yours?

References

• Document
• HUAWEI Developer

“No available product for service release” warning in Appgallery Connect Wear Engine Application was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

How do you take a screenshot on a device that has no power button, no volume keys, and a single crown button? That is the reality of building apps for Kids Watches running HarmonyOS NEXT. The usual hardware key combo simply does not exist here, so native screen capture is off the table.

In this tutorial, we will build a reusable ScreenshotSaver class in ArkTS that captures any app UI and saves it straight to the gallery. We will rely on two HarmonyOS capabilities: getComponentSnapshot() to grab the rendered view, and the photoAccessHelper API to persist the result into the system gallery.

Why Kids Watches Have No Native Screenshot

Kids Watches are intentionally minimal devices. They have one crown button for navigation, which means the classic “press two buttons at once” screenshot gesture cannot exist.

The good news? If you only need a screenshot of your app’s content, not the full system screen, you can capture the root component of your page instead.

The Workaround in a Nutshell

The solution follows a three-stage pipeline:

1. Snapshot: getComponentSnapshot() returns a ComponentSnapshot object that gives you a PixelMap of any component with an id.
2. Encode: The Image Kit’s ImagePacker compresses that PixelMap into PNG bytes.
3. Save: The photoAccessHelper API creates an image asset in the system gallery and attaches the bytes to it.

Let’s build it step by step.

Step 1: Declare the Permission

Saving into the gallery requires the ohos.permission.WRITE_IMAGEVIDEO permission. Add it to your module.json5 file first, because the code will request it from the user at runtime.

{
  "name": "ohos.permission.WRITE_IMAGEVIDEO",
  "reason": "$string:module_desc",
  "usedScene": {
    "abilities": [
      "EntryAbility"
    ],
    "when": "inuse"
  },
}

Step 2: Build the ScreenshotSaver Class

The core of the workaround is a small utility class. First, we need a helper that asks the user for gallery write access and reports whether it was granted:

// ScreenshotSaver.ets (part 1: permission handling)
import { abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit';

private static async ensurePermission(context: common.UIAbilityContext): Promise<boolean> {
  const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
  try {
    const result = await atManager.requestPermissionsFromUser(context, [ScreenshotSaver.PERMISSION]);
    return result.authResults.length > 0 && result.authResults[0] === 0;
  } catch (err) {
    const e = err as BusinessError;
    console.error(`${ScreenshotSaver.TAG} requestPermissions failed: ${e.code} - ${e.message}`);
    return false;
  }
}

A nice detail here: if the permission was already granted, the dialog never appears and the method returns immediately.

With permission out of the way, the capture pipeline itself is surprisingly compact:

// ScreenshotSaver.ets (part 2: capture, encode, save)
import { image } from '@kit.ImageKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';

static async captureAndSave(uiContext: UIContext, rootComponentId: string): Promise<void> {
  let pixelMap: image.PixelMap | undefined = undefined;
  try {
    const context = uiContext.getHostContext() as common.UIAbilityContext;
    // 0. Ensure WRITE_IMAGEVIDEO is actually granted.
    const granted: boolean = await ScreenshotSaver.ensurePermission(context);
    if (!granted) {
      console.error(`${ScreenshotSaver.TAG} WRITE_IMAGEVIDEO not granted`);
      uiContext.getPromptAction().showToast({ message: 'No gallery-write permission' });
      return;
    }
    // 1. Snapshot the screen.
    pixelMap = await uiContext.getComponentSnapshot().get(rootComponentId, { waitUntilRenderFinished: true });
    // 2. Encode it to PNG bytes.
    const packer = image.createImagePacker();
    const png = await packer.packToData(pixelMap, { format: 'image/png', quality: 100 });
    packer.release();
    // 3. Save to the gallery
    const helper = photoAccessHelper.getPhotoAccessHelper(context);
    const request =
      photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, photoAccessHelper.PhotoType.IMAGE, 'png');
    request.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, png);
    await helper.applyChanges(request);
    uiContext.getPromptAction().showToast({ message: 'Saved to gallery' });
  } catch (err) {
    const e = err as BusinessError;
    console.error(`ScreenshotSaver failed: ${e.code} - ${e.message}`);
    try {
      uiContext.getPromptAction().showToast({ message: 'Save failed' });
    } catch (error) {
      console.error(`showToast failed: ${e.code} - ${e.message}`);
    }
  } finally {
    if (pixelMap !== undefined) {
      pixelMap.release();
    }
  }
}

Step 3: Wire It into Your Page

Using the class takes two moves. First, give the container you want to capture a unique id:

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('Test')
    }
    .id('SCREEN_ROOT')
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
    .justifyContent(FlexAlign.Center)
  }
}

Then call the saver once the first frame has been rendered:

aboutToAppear(): void {
  setTimeout(() => {
    ScreenshotSaver.captureAndSave(this.getUIContext(), 'SCREEN_ROOT')
  }, 1000)
}

A complete example for a ScreenshotSaver class:

import { image } from '@kit.ImageKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit';
import { UIContext } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * HOW TO USE
 * ---
 * 0. Make sure that 'ohos.permission.WRITE_IMAGEVIDEO' is added in module.json5.
 * 1. Give the container to capture a unique id:
 * ```
 * Column() {
 *   // ... your page content ...
 * }
 * .width('100%')
 * .height('100%')
 * .id('SCREEN_ROOT')
 * ```
 * 2. Call it from anywhere:
 * ```
 * import { ScreenshotSaver } from '../util/ScreenshotSaver';
 *
 * aboutToAppear(): void {
 *   setTimeout(() => {
 *     ScreenshotSaver.captureAndSave(this.getUIContext(), 'SCREEN_ROOT');
 *   }, 1000);
 * }
 * ```
 */
export class ScreenshotSaver {
  private static readonly TAG: string = 'ScreenshotSaver';
  private static readonly PERMISSION: Permissions = 'ohos.permission.WRITE_IMAGEVIDEO';

  /**
   * Snapshots the component with the given id and saves it straight to the
   * gallery. Requests ohos.permission.WRITE_IMAGEVIDEO first.
   *
   * @param uiContext        The current UI context, e.g. this.getUIContext().
   * @param rootComponentId  The .id set on the container to capture.
   */
  static async captureAndSave(uiContext: UIContext, rootComponentId: string): Promise<void> {
    let pixelMap: image.PixelMap | undefined = undefined;
    try {
      const context = uiContext.getHostContext() as common.UIAbilityContext;
      // 0. Ensure WRITE_IMAGEVIDEO is actually granted.
      const granted: boolean = await ScreenshotSaver.ensurePermission(context);
      if (!granted) {
        console.error(`${ScreenshotSaver.TAG} WRITE_IMAGEVIDEO not granted`);
        uiContext.getPromptAction().showToast({ message: 'No gallery-write permission' });
        return;
      }
      // 1. Snapshot the screen.
      pixelMap = await uiContext.getComponentSnapshot().get(rootComponentId, { waitUntilRenderFinished: true });
      // 2. Encode it to PNG bytes.
      const packer = image.createImagePacker();
      const png = await packer.packToData(pixelMap, { format: 'image/png', quality: 100 });
      packer.release();
      // 3. Save to the gallery
      const helper = photoAccessHelper.getPhotoAccessHelper(context);
      const request =
        photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, photoAccessHelper.PhotoType.IMAGE, 'png');
      request.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, png);
      await helper.applyChanges(request);
      uiContext.getPromptAction().showToast({ message: 'Saved to gallery' });
    } catch (err) {
      const e = err as BusinessError;
      console.error(`ScreenshotSaver failed: ${e.code} - ${e.message}`);
      try {
        uiContext.getPromptAction().showToast({ message: 'Save failed' });
      } catch (error) {
        console.error(`showToast failed: ${e.code} - ${e.message}`);
      }
    } finally {
      if (pixelMap !== undefined) {
        pixelMap.release();
      }
    }
  }

  // Requests WRITE_IMAGEVIDEO. Returns true when granted (already-granted returns
  // immediately with no dialog); false when denied or the app cannot hold it.
  private static async ensurePermission(context: common.UIAbilityContext): Promise<boolean> {
    const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
    try {
      const result = await atManager.requestPermissionsFromUser(context, [ScreenshotSaver.PERMISSION]);
      return result.authResults.length > 0 && result.authResults[0] === 0;
    } catch (err) {
      const e = err as BusinessError;
      console.error(`${ScreenshotSaver.TAG} requestPermissions failed: ${e.code} - ${e.message}`);
      return false;
    }
  }
}

Tips and Common Pitfalls

Pro Tip: Always pass waitUntilRenderFinished: true when grabbing a snapshot. Without it, you can capture a half-drawn frame and end up with a blank or partially rendered PNG in the gallery.

A few more lessons worth remembering:

• Delay the first capture. Calling the saver directly inside aboutToAppear() can race against the first render. A one-second setTimeout keeps things safe.
• Snapshot the component, not the screen. This approach only captures your own UI tree. That is a feature for privacy, but do not expect status bar or system UI in the output.

Conclusion

Native screenshots may be impossible on Kids Watches, but a well-designed workaround gets you the same result with two public APIs. getComponentSnapshot() hands you the rendered view, the Image Kit encodes it, and photoAccessHelper files it neatly into the gallery. The whole solution fits in a single reusable class you can drop into any HarmonyOS NEXT wearable project. Try it in your next Kids Watch app, and you will never be blocked by a missing button combo again.

References

• ComponentSnapshot API Reference
• PhotoAccessHelper API Reference
• Permission: ohos.permission.WRITE_IMAGEVIDEO
• Image Kit Reference

How to Take a Screenshot on a Kids Watch with HarmonyOS? was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

Every new platform has a “first run” milestone, and it is rarely as smooth as the marketing page promises. Between toolchains, device pairing, and signing certificates, getting a single “Hello World” onto a real wearable can quietly eat an entire afternoon. That is exactly the gap this guide closes.

In this tutorial, you will learn how to set up the HarmonyOS Next development environment, prepare three different kinds of target devices (a physical smart wearable, the built-in emulator, and the Previewer), handle application signing both automatically and manually, and finally launch your first application with DevEco Studio.

By the end, your app will be running on a device you can actually hold in your hand.

Setting Up the Development Environment

Before anything else, you need two things installed and wired together: DevEco Studio, and its command line toolchains.

Installing DevEco Studio

DevEco Studio is Huawei’s official IDE for HarmonyOS development, and it is the backbone of everything in this guide. If you have used Android Studio or IntelliJ before, the layout will feel familiar within minutes, which lowers the learning curve considerably.

Download the appropriate version for your operating system from the official Huawei developer portal at:

DevEco Studio — HUAWEI Developers

Configuring the Toolchains Path

Installing the IDE is not quite the end of setup. The HarmonyOS toolchains, which include the HDC (HarmonyOS Device Connector) utility you will rely on later for device communication, need to be reachable from your system’s PATH environment variable.

Add the following directory to Environment Variables > PATH:

{Your_DevEco_Studio_Path}/sdk/default/openharmony/toolchains

Important note: Without this step, commands like hdc will simply not be recognized in your terminal, which is a surprisingly common stumbling block for first-time HarmonyOS developers.

Preparing Your Target Devices

HarmonyOS Next gives you three distinct ways to see your app in action, and each one serves a different point in your development loop. Let’s walk through all three.

Using a Physical Device (Smart Wearable)

There is nothing quite like seeing your UI render on an actual watch. But before DevEco Studio can talk to your wearable, you need to unlock its developer mode, and Huawei has hidden this behind a gesture-based easter egg.

Here is how to enable it:

1. In the watch’s Settings, open the watch information screen and locate “Software Version”.
2. Tap “Software Version” 3 times in a row. Developer Options will be enabled.
3. You will now find Developer Options under Settings > System > Developer Options.
4. Inside Developer Options, enable both “HDC Debugging” and “Debug via Wi-Fi”.

Using the Emulator

No physical device on your desk? No problem. DevEco Studio ships with a full emulator, which is perfect for testing layouts across different device profiles without buying hardware.

Setting it up takes only a few clicks:

1. Go to Tools > Device Manager in DevEco Studio.
2. Click New Emulator and select a device definition, such as a Phone or a Wearable model.
3. Choose the system image you want, download it, and let it run.
4. Click Finish to create your virtual device.

Using the Previewer

Sometimes a full emulator boot is overkill. When you are fine-tuning a layout or just want to sanity-check your ArkTS UI code, the Previewer gives you near-instant visual feedback without launching an entire operating system.

1. Open your UI code file, for example Index.ets.
2. Click the Previewer button, usually located on the right side of the editor.
3. Make sure the module is set to entry and the profile is correct, and you will see a live visual rendering of your code.

Configuring Application Signing

Here is the part that trips up most newcomers: HarmonyOS applications must be signed before they will install on any device. Unlike some platforms where debug builds work out of the box, HarmonyOS Next requires a deliberate signing configuration.

Both automatic and manual signing live in the same place: File > Project Structure > Signing Configs.

Automatic Signing (Recommended)

For the vast majority of developers, automatic signing is the right choice. DevEco Studio generates the required certificates and profiles for you, applying the configuration without any manual certificate juggling.

1. Go to File > Project Structure > Signing Configs.
2. Check the box for “Automatically generate signature”.
3. Wait for DevEco Studio to generate the necessary files and apply the configuration.

That is genuinely all there is to it. Unless you have a specific organizational requirement, stop here and enjoy the time you just saved.

Manual Signing (Optional)

Manual signing exists for developers who need explicit control over their certificates and device registrations, which is common in enterprise settings or when working with registered hardware. If automatic signing works for you, skip this section entirely.

The manual process has one important prerequisite you should understand first: debug profiles are tied to specific devices, and each device is identified by a UDID (Unique Device Identifier). So the manual flow becomes a chain: get the device’s UDID, register it, create a certificate, then create a profile that binds them together.

Retrieving the Device’s UDID:

First, make sure both the smart wearable and your computer are connected to the same Wi-Fi network. Then:

1. On the watch, go to Settings > System > Developer Options and open the “Debug via Wi-Fi” setting to find the device’s IP address.

2. Connect to the watch over the network:

hdc tconn {WATCH_IP_ADDRESS:PORT}

For example:

hdc tconn 172.10.10.1:11111

3. Retrieve the device’s UDID:

hdc shell bm get --udid

Registering the UDID in AppGallery Connect:

With the UDID in hand, head to Huawei’s developer console:

1. Open AppGallery Connect and navigate to Certificates, app IDs, and Profiles > Devices.
2. Click Add Device and register your device’s UDID.

Creating a Certificate Signing Request (CSR):

Next, you need a CSR (Certificate Signing Request), which DevEco Studio can generate for you:

1. In DevEco Studio, go to Build > Generate Key and CSR.
2. Fill in the required fields to create your key store and the resulting CSR file.

Creating a Debug Certificate:

Now the certificate itself:

1. In AppGallery Connect, go to Certificates, app IDs, and Profiles > Certificates.
2. Click New Certificate and create a new debug certificate, typically by uploading the CSR you just generated.

Creating a Debug Profile

Finally, you tie everything together with a debug profile:

1. In AppGallery Connect, go to Certificates, app IDs, and Profiles > Profiles.
2. Click Add and create a new debug profile with these settings:

• App Name: Select your application in AppGallery Connect.
• Profile Name: Anything you like; it is just a label.
• Type: Debug.
• Certificate: Choose the certificate you created in the previous step.
• Device: Choose the device you registered earlier.

Once the profile is downloaded and applied in your project’s Signing Configs, your app is cleared for installation on that specific device.

Running the Application

With the environment configured, the device prepared, and signing sorted, this is the satisfying part.

Selecting the Target

Look at the top toolbar in DevEco Studio and use the dropdown menu to pick where your app will run:

• Your physical device, if it is connected via HDC.
• Your emulator instance, if one is currently running.

Note that the Previewer does not appear in this list. It runs independently in the editor pane and does not require any target selection.

Launching the App

Click the green Run (triangle) icon to build and install your application on the selected target. Alternatively, click the Debug (bug) icon to launch in debug mode, which lets you set breakpoints and inspect logs and variables as the app runs.

Moments later, your application should appear on the device. If it does, congratulations, you have officially joined the HarmonyOS Next developer community.

Tips to Avoid Common Pitfalls

Before you close this tab, a few lessons that will save you time:

• Enable Developer Options on the wearable before troubleshooting connection issues. HDC debugging cannot start without it.
• Keep the watch and the computer on the same Wi-Fi network during wireless debugging. Different subnets are a classic silent failure.
• Prefer automatic signing unless you truly need manual control. The manual flow with UDIDs, CSRs, certificates, and profiles is powerful but easy to get wrong on the first pass.
• Use the Previewer for fast UI iteration and reserve full device runs for behavior testing.

Conclusion

Running your first HarmonyOS Next application comes down to four pillars: a properly configured DevEco Studio installation, a prepared target device, a valid signing configuration, and a target selection in the toolbar. The environment setup is a one-time investment, and after it is done, your edit-run cycle becomes fast enough to support real, iterative development on wearables. If you are building for Huawei’s ecosystem in 2026, mastering this foundation is the gateway to everything HarmonyOS Next has to offer, from ArkTS UI development to distributed cross-device experiences.

References

• DevEco Studio Download: DevEco Studio — HUAWEI Developers
• Huawei HarmonyOS Next Official Documentation: Application Development Overview-Getting Started — HUAWEI Developers
• HarmonyOS Application Signing Guide: Configuring a Debug Signature-Coding and Debugging — HUAWEI Developers
• Debugging HarmonyOS Applications: Debugging Overview-Debugging Your App-Coding and Debugging — HUAWEI Developers

How to Run Your First HarmonyOS Next App in 2026? A Complete Beginner Tutorial was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.